App SDK Reference (@brainerce/app-sdk)

npm install @brainerce/app-sdk

import { ManifestBuilder } from '@brainerce/app-sdk';

const manifest = new ManifestBuilder()
  .name('My App')
  .version('1.0.0')
  .connectorIntegration('https://my-app.com', {
    pushProduct: '/sync/push-product',
    pullOrders: '/sync/pull-orders',
    connectionStatus: '/sync/connection-status',
    reconcile: '/sync/reconcile',
  })
  .hooks({
    onInstall: '/hooks/on-install',
    onUninstall: '/hooks/on-uninstall',
    onConfigUpdate: '/hooks/on-config-update',
  })
  .health('/health')
  .eventSubscriptions(['product.created', 'order.created'])
  .build(); // throws ManifestValidationError if invalid

import { validateManifest } from '@brainerce/app-sdk';

const result = validateManifest(myManifest);
if (!result.valid) {
  console.error(result.errors);
  // [{ field: 'name', message: 'name is required and must be a non-empty string' }]
}

import { BrainerceAppClient } from '@brainerce/app-sdk';

const client = new BrainerceAppClient({
  token: 'app_inst_abc123', // Required: installation token
  installationId: 'inst_01HXYZ', // Required: must match the token's installation
  baseUrl: 'https://api.brainerce.com', // Optional (this is the default)
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
});

// Write secrets (write-only — you cannot read secrets back). Existing keys
// not included in the call are preserved.
await client.updateSecrets({ apiKey: 'new-key-123' });

// Create or update a mapping (idempotent; recommended for sync loops)
await client.upsertResourceMapping({
  resourceType: 'product',
  internalId: 'brainerce-product-id',
  externalId: '12345',
  externalUrl: 'https://platform.com/products/12345',
  platformCode: 'tiktok', // Required: matches an installed app's `App.platformCode`
  syncStatus: 'synced', // 'synced' | 'pending' | 'error' | 'stale'
});

// List mappings for a resource type (paginated)
const { data, meta } = await client.getResourceMappings({ resourceType: 'product' });
// data: Array<{ id, storeId, installationId, resourceType, internalId, externalId,
//               externalUrl, platformCode, syncStatus, lastSyncedAt, lastSyncError,
//               metadata, createdAt, updatedAt }>
// meta: { page, limit, total, totalPages }

const result = await client.request<MyType>(
  'GET',
  `/api/v1/installations/${installationId}/mappings`
);

interface BaseAppRequest {
  storeId: string;
  installationId: string;
  config: Record<string, unknown>;
  secrets: Record<string, unknown>;
}

interface PushProductRequest extends BaseAppRequest {
  productId: string;
  productData: Record<string, unknown>; // Brainerce product format
  externalId?: string; // If updating existing
}

interface PushProductResponse {
  externalId: string;
  externalUrl?: string;
}

interface PullOrdersRequest extends BaseAppRequest {
  since?: string; // ISO 8601 date — only fetch orders after this
  page?: number;
  limit?: number;
}

interface PullOrdersResponse {
  orders: Record<string, unknown>[];
  hasMore?: boolean;
  nextPage?: number;
}

type ConnectionStatusRequest = BaseAppRequest;

interface ConnectionStatusResponse {
  connected: boolean;
  scopes?: string[];
  hasRequiredScopes?: boolean;
  details?: Record<string, unknown>;
  error?: string;
}

interface ReconcileRequest extends BaseAppRequest {
  resourceType: string; // "product", "order", etc.
  since?: string;
}

interface ReconcileResponse {
  reconciled: number;
  created: number;
  updated: number;
  deleted: number;
  errors?: string[];
}

interface CreatePaymentIntentRequest extends BaseAppRequest {
  amount: number;
  currency: string;
  returnUrl?: string;
  metadata?: Record<string, unknown>;
  customerId?: string;
  description?: string;
}

interface PaymentIntentResponse {
  id: string;
  /**
   * The provider's payment IDENTIFIER. Put a URL here only if it genuinely is
   * one; storefronts read `clientSdk.renderArg` first for anything they have
   * to open or render.
   */
  clientSecret: string;
  status:
    | 'requires_payment_method'
    | 'requires_confirmation'
    | 'requires_action'
    | 'processing'
    | 'succeeded'
    | 'canceled';
  amount: number;
  currency: string;
  metadata?: Record<string, unknown>;
  /** Runtime clientSdk overrides, merged with your manifest config by core. */
  clientSdk?: {
    initConfig?: Record<string, unknown>;
    /**
     * What the storefront hands to the render step: the iframe `src`, the
     * redirect target, or the argument passed to `renderMethod`. Overrides
     * `clientSecret`. If your provider returns a hosted payment page, set it
     * here.
     */
    renderArg?: string;
  };
}

interface ConfirmPaymentRequest extends BaseAppRequest {
  intentId: string;
  paymentMethodId?: string;
}

interface RefundRequest extends BaseAppRequest {
  intentId: string;
  amount?: number; // Partial refund amount (omit for full refund)
  reason?: string;
  metadata?: Record<string, unknown>;
}

interface RefundResponse {
  id: string;
  paymentId: string;
  amount: number;
  currency: string;
  status: 'pending' | 'succeeded' | 'failed' | 'canceled';
}

interface OAuthStartRequest extends BaseAppRequest {
  callbackUrl: string; // URL to redirect back to after authorization
}

interface OAuthStartResponse {
  redirectUrl: string; // Full URL to redirect the user to
}

interface OAuthCallbackRequest extends BaseAppRequest {
  originalPayload: Record<string, unknown>; // Query params/body from the OAuth redirect
  originalHeaders: Record<string, string>;
}

interface OAuthCallbackResponse {
  success: boolean;
  secrets?: Record<string, unknown>; // Credentials to store (encrypted automatically)
  config?: Record<string, unknown>; // Config updates
  error?: string;
}

type HookRequest = BaseAppRequest;

interface HookResponse {
  success: boolean;
  message?: string;
}

interface InboundWebhookRequest extends BaseAppRequest {
  originalPayload: unknown;
  originalHeaders: Record<string, string>;
}

interface InboundWebhookResponse {
  received: boolean;
  processed?: boolean;
  data?: Record<string, unknown>;
}

type IntegrationType = 'payment' | 'connector' | 'shipping' | 'custom';

interface AppManifest {
  name: string;
  version: string; // Semver: "1.0.0"
  integration: IntegrationConfig;
  hooks?: ManifestHooks;
  health?: string; // e.g. "/health"
  eventSubscriptions?: string[]; // e.g. ["product.created", "order.updated"]
}

interface IntegrationConfig {
  type: IntegrationType;
  serviceUrl: string; // Where your service runs
  paymentContract?: { endpoints: PaymentEndpoints };
  connectorContract?: { endpoints: ConnectorEndpoints; oauth?: OAuthConfig };
  shippingContract?: { endpoints: ShippingEndpoints };
  customContract?: Record<string, unknown>;
}

interface ConnectorEndpoints {
  pushProduct?: string;
  pullOrders?: string;
  connectionStatus?: string;
  reconcile?: string;
}

interface PaymentEndpoints {
  createPaymentIntent: string; // Required
  confirmPayment: string; // Required
  refund: string; // Required
  connectionStatus?: string;
}

interface ShippingEndpoints {
  getRates?: string;
  createShipment?: string;
}

interface OAuthConfig {
  startPath: string; // e.g. "/oauth/start"
  callbackPath: string; // e.g. "/oauth/callback"
}

interface ManifestHooks {
  onInstall?: string;
  onUninstall?: string;
  onConfigUpdate?: string;
}

type AppScope =
  | 'products:read'
  | 'products:write'
  | 'orders:read'
  | 'orders:write'
  | 'inventory:read'
  | 'inventory:write'
  | 'customers:read'
  | 'customers:write';

// Full list
import { APP_SCOPES } from '@brainerce/app-sdk';

// Human-readable descriptions
import { SCOPE_DESCRIPTIONS } from '@brainerce/app-sdk';
// { 'products:read': 'Read product data', 'products:write': 'Create and update products', ... }

type DomainEventType =
  | 'product.created'
  | 'product.updated'
  | 'product.deleted'
  | 'order.created'
  | 'order.updated'
  | 'inventory.changed';

interface DomainEvent {
  event: DomainEventType;
  storeId: string;
  installationId: string;
  timestamp: string; // ISO 8601
  data: Record<string, unknown>; // Event-specific payload
}

// Full list
import { DOMAIN_EVENT_TYPES } from '@brainerce/app-sdk';

# Ed25519 public key from the Brainerce platform (NOT sensitive)
BRAINERCE_PUBLIC_KEY=MCowBQYDK2VwAyEA...

import { verifyWebhookSignature } from '@brainerce/app-sdk';

app.post('/webhooks', (req, res) => {
  const isValid = verifyWebhookSignature({
    body: req.rawBody, // Raw request body as string
    signature: req.headers['x-brainerce-signature'], // Hex-encoded HMAC
    timestamp: req.headers['x-timestamp'], // ISO 8601
    secret: savedWebhookSecret, // From your DB (received during onInstall)
    maxAgeMs: 300_000, // Optional: max age (default 5 min)
  });

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
});

import { AppClientError, ManifestValidationError } from '@brainerce/app-sdk';

// Thrown by BrainerceAppClient on HTTP errors
class AppClientError extends Error {
  status: number;
  data?: unknown;
}

// Thrown by ManifestBuilder.build() on validation failure
class ManifestValidationError extends Error {
  errors: Array<{ field: string; message: string }>;
}