JSPM

  • Created
  • Published
  • Downloads 582
  • Score
    100M100P100Q114118F
  • License MIT

23blocks SDK - unified meta-package re-exporting all blocks and utilities

Package Exports

  • @23blocks/sdk
  • @23blocks/sdk/package.json

Readme

@23blocks/sdk

The complete 23blocks SDK - all blocks in a single package with automatic token management.

npm version License: MIT

Installation

npm install @23blocks/sdk

Overview

This is the recommended package for most users. It provides:

  • All blocks - Every 23blocks feature in one package
  • Simple client - Single factory function to create the client
  • Token management - Automatic token storage and refresh
  • Type safety - Full TypeScript support

Quick Start

import { create23BlocksClient } from '@23blocks/sdk';

// Create client with service URLs
const client = create23BlocksClient({
  apiKey: 'your-api-key',
  urls: {
    authentication: 'https://auth.yourapp.com',
    // Add other services as needed
    // products: 'https://products.yourapp.com',
    // crm: 'https://crm.yourapp.com',
  },
});

// Sign in - tokens are stored automatically
const { user } = await client.auth.signIn({
  email: 'user@example.com',
  password: 'password',
});
console.log('Welcome', user.email);

// All subsequent requests include auth automatically
const currentUser = await client.auth.getCurrentUser();

// Sign out - tokens are cleared automatically
await client.auth.signOut();

Configuration

ClientConfig Options

const client = create23BlocksClient({
  // Required: Service URLs (only configure what you need)
  urls: {
    authentication: 'https://auth.yourapp.com',
    products: 'https://products.yourapp.com',
    crm: 'https://crm.yourapp.com',
    // ... other services
  },

  // Required: Your API key
  apiKey: 'your-api-key',

  // Optional: Tenant ID for multi-tenant setups
  tenantId: 'tenant-123',

  // Optional: Authentication mode (default: 'token')
  authMode: 'token', // 'token' | 'cookie'

  // Optional: Token storage (default: 'localStorage' in browser, 'memory' in SSR)
  storage: 'localStorage', // 'localStorage' | 'sessionStorage' | 'memory'

  // Optional: Additional headers for every request
  headers: { 'X-Custom-Header': 'value' },

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,
});

Service URLs

Each microservice has its own URL. Only configure the services you need:

interface ServiceUrls {
  authentication?: string;  // Auth, users, roles
  search?: string;          // Search, favorites
  products?: string;        // Products, cart, catalog
  crm?: string;             // Contacts, leads, opportunities
  content?: string;         // CMS posts, comments
  geolocation?: string;     // Addresses, locations
  conversations?: string;   // Messages, notifications
  files?: string;           // File uploads
  forms?: string;           // Form builder
  assets?: string;          // Asset tracking
  campaigns?: string;       // Marketing campaigns
  company?: string;         // Company settings
  rewards?: string;         // Rewards, loyalty
  sales?: string;           // Orders, payments
  wallet?: string;          // Digital wallet
  jarvis?: string;          // AI assistant
  onboarding?: string;      // User onboarding
  university?: string;      // Learning management
}

Note: Accessing a service without a configured URL will throw an error with a helpful message.

Token Mode (Default)

Tokens are stored in browser storage and attached to requests automatically:

const client = create23BlocksClient({
  apiKey: 'your-api-key',
  urls: { authentication: 'https://auth.yourapp.com' },
  authMode: 'token',        // default
  storage: 'localStorage',  // default in browser
});

Backend manages authentication via httpOnly cookies:

const client = create23BlocksClient({
  apiKey: 'your-api-key',
  urls: { authentication: 'https://auth.yourapp.com' },
  authMode: 'cookie',
});

SSR / Server-Side Usage

For server-side rendering, use memory storage and pass tokens manually:

const client = create23BlocksClient({
  apiKey: 'your-api-key',
  urls: { authentication: 'https://auth.yourapp.com' },
  storage: 'memory',
  headers: {
    Authorization: `Bearer ${tokenFromRequest}`,
  },
});

Multi-Tenant Setup

const client = create23BlocksClient({
  apiKey: 'your-api-key',
  urls: { authentication: 'https://auth.yourapp.com' },
  tenantId: 'tenant-123',
});

Authentication

Sign In

// Required: email, password
const { user, accessToken, refreshToken, expiresIn } = await client.auth.signIn({
  email: 'user@example.com',
  password: 'password',
});

// In token mode, tokens are automatically stored
// In cookie mode, backend sets httpOnly cookies

Sign Up (Registration)

// Sign up with required fields only
const { user, accessToken, message } = await client.auth.signUp({
  email: 'new@example.com',         // Required
  password: 'password',              // Required
  passwordConfirmation: 'password',  // Required - must match password
});

// Sign up with optional fields
const { user, accessToken, message } = await client.auth.signUp({
  // Required
  email: 'new@example.com',
  password: 'password',
  passwordConfirmation: 'password',

  // Optional
  name: 'John Doe',
  username: 'johndoe',
  roleId: 'role-uuid',
  confirmSuccessUrl: 'https://yourapp.com/confirmed',  // Redirect after email confirmation
  timeZone: 'America/New_York',
  preferredLanguage: 'en',
  payload: { referralCode: 'ABC123' },  // Custom data
  subscription: 'premium-plan',          // Subscription model ID
});

Note: If email confirmation is enabled, accessToken will be undefined. The user must confirm their email before signing in.

Sign Out

await client.auth.signOut();
// Tokens are automatically cleared (token mode) or cookies invalidated (cookie mode)

Get Current User

const user = await client.auth.getCurrentUser();
// Returns user with role, avatar, and profile included

Email Confirmation

// Confirm email with token from email link
const user = await client.auth.confirmEmail('confirmation-token');

// Resend confirmation email
await client.auth.resendConfirmation({
  email: 'user@example.com',
  confirmSuccessUrl: 'https://yourapp.com/confirmed',  // Optional
});

Password Reset

// Request password reset email
await client.auth.requestPasswordReset({
  email: 'user@example.com',
  redirectUrl: 'https://yourapp.com/reset',  // Optional
});

// Update password with reset token
await client.auth.updatePassword({
  password: 'newPassword',
  passwordConfirmation: 'newPassword',
  resetPasswordToken: 'token-from-email',
});

Token Utilities

// Check if authenticated (token mode only, returns null in cookie mode)
const isLoggedIn = client.isAuthenticated();

// Get tokens manually (token mode only)
const accessToken = client.getAccessToken();
const refreshToken = client.getRefreshToken();

// Set tokens manually (useful for SSR hydration)
client.setTokens(accessToken, refreshToken);

// Clear session
client.clearSession();

Available Blocks

The client provides access to all blocks:

Block Description
client.auth Authentication with managed tokens
client.authentication Full authentication block
client.search Search and favorites
client.products Products, categories, cart
client.crm CRM - contacts, accounts, leads
client.content CMS - posts, comments
client.geolocation Addresses, locations
client.conversations Messages, notifications
client.files File uploads
client.forms Form builder
client.assets Asset tracking
client.campaigns Marketing campaigns
client.company Company settings
client.rewards Rewards and loyalty
client.sales Orders and payments
client.wallet Digital wallet
client.jarvis AI assistant
client.onboarding User onboarding
client.university Learning management

Usage Examples

Products

// Requires urls.products to be configured
const { data: products, meta } = await client.products.products.list({
  limit: 20,
  categoryId: 'category-123',
});

// Get product
const product = await client.products.products.get('product-id');

// Add to cart
const cart = await client.products.cart.addItem({
  productId: 'product-id',
  quantity: 2,
});

// Checkout
const order = await client.products.cart.checkout({
  shippingAddressId: 'address-id',
  paymentMethodId: 'payment-id',
});
// Requires urls.search to be configured
const { results, totalRecords } = await client.search.search.search({
  query: 'laptop',
  limit: 20,
});

// Suggestions
const suggestions = await client.search.search.suggest('lap', 5);

// Favorites
await client.search.favorites.add({
  entityUniqueId: 'product-123',
  entityType: 'Product',
});

const { data: favorites } = await client.search.favorites.list();

CRM

// Requires urls.crm to be configured
const { data: contacts } = await client.crm.contacts.list({ limit: 20 });

// Create lead
const lead = await client.crm.leads.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
});

// Create opportunity
const opp = await client.crm.opportunities.create({
  name: 'Enterprise Deal',
  accountId: 'account-id',
  value: 50000,
});

Error Handling

import { isBlockErrorException, ErrorCodes } from '@23blocks/sdk';

try {
  await client.auth.signIn({ email, password });
} catch (error) {
  if (isBlockErrorException(error)) {
    switch (error.code) {
      case ErrorCodes.INVALID_CREDENTIALS:
        console.log('Invalid email or password');
        break;
      case ErrorCodes.UNAUTHORIZED:
        console.log('Session expired');
        break;
      case ErrorCodes.VALIDATION_ERROR:
        console.log('Validation error:', error.message);
        break;
      case ErrorCodes.NETWORK_ERROR:
        console.log('Network error');
        break;
      default:
        console.log(error.message);
    }
  }
}

Advanced: Custom Transport

For advanced users who need custom transport configuration:

import { createHttpTransport, createAuthenticationBlock } from '@23blocks/sdk';

const transport = createHttpTransport({
  baseUrl: 'https://auth.yourapp.com',
  headers: () => {
    const token = localStorage.getItem('access_token');
    return {
      'x-api-key': 'your-api-key',
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    };
  },
  timeout: 60000,
});

const auth = createAuthenticationBlock(transport, {
  apiKey: 'your-api-key',
});

// Use the block directly
const { user } = await auth.auth.signIn({ email, password });

TypeScript

All types are exported and can be used directly:

import type {
  // Client types
  Blocks23Client,
  ClientConfig,
  ServiceUrls,
  AuthMode,
  StorageType,

  // Auth types
  User,
  SignInRequest,
  SignInResponse,
  SignUpRequest,
  SignUpResponse,

  // Product types
  Product,
  Cart,

  // Core types
  PageResult,
  BlockError,
} from '@23blocks/sdk';

Framework-Specific Packages

For framework-specific features:

Individual Blocks

If you only need specific functionality, install individual blocks:

npm install @23blocks/transport-http @23blocks/block-authentication @23blocks/block-search

See the main README for the complete list of available packages.

License

MIT - Copyright (c) 2024 23blocks