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). The keys you send
// are merged over the stored ones: keys not included in the call are preserved,
// so sending only a refreshed accessToken keeps the stored refreshToken.
await client.updateSecrets({ apiKey: 'new-key-123' });

// A key sent as null is deleted.
await client.updateSecrets({ oldApiKey: null });

// 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;
  metadata?: Record<string, unknown>;
}

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>;
}

// Itemized invoice lines the core sets on CreatePaymentIntentRequest.lineItems.
// Forward them to your invoicing endpoint as they are: the core guarantees that
// price * quantity across all lines equals `amount` (major units).
interface PaymentLineItem {
  name: string;
  quantity: number;
  price: number; // unit price, same currency as the payment, major units
  sku?: string;
}

// CreatePaymentIntentRequest also carries (all optional):
//   lineItems?: PaymentLineItem[];
//   metadata?: Record<string, unknown>; // core sets checkoutId, storeId, fullName, phone, email, successUrl, cancelUrl, notifyUrl
//   returnUrl?: string; customerId?: string; description?: string;

// RefundRequest also carries providerData, the original payment's Payment.providerData
// verbatim. Read provider lookup keys (for example a document number needed to cancel an
// invoice) from it, not from metadata.
//   providerData?: Record<string, unknown>;

// RefundResponse also carries the credit note a provider issued with the refund. Report
// only what the provider returned: the number is a legal document reference.
//   creditNoteNumber?: string;
//   creditNoteUrl?: string;

// Connector sync contract: inventory, coupons and deletes.
interface PushInventoryRequest extends BaseAppRequest {
  productId: string;
  variantId?: string;
  stock: number;
  trackingMode: string;
  externalId?: string;
}
interface PushInventoryResponse {
  success: boolean;
  externalId?: string;
}

interface PushCouponRequest extends BaseAppRequest {
  couponId: string;
  couponData: Record<string, unknown>;
  externalId?: string;
}
interface PushCouponResponse {
  externalId: string;
  externalUrl?: string;
}

interface DeleteResourceRequest extends BaseAppRequest {
  resourceType: string;
  externalId: string;
  internalId?: string;
}
interface DeleteResourceResponse {
  success: boolean;
  error?: string;
}

type PaymentWebhookEventType =
  | 'payment.succeeded'
  | 'payment.failed'
  | 'payment.refunded'
  | 'payment.partially_refunded'
  | 'payment.disputed'
  | 'payment.unknown';

interface PaymentMethodDetails {
  brand?: string;
  last4?: string;
  expMonth?: number;
  expYear?: number;
  [key: string]: unknown;
}

interface NormalizedPaymentEvent {
  type: PaymentWebhookEventType;
  // At least one lookup key, so the core can find the checkout or payment.
  checkoutId?: string;
  paymentIntentId?: string;
  paymentExternalId?: string;
  // payment.succeeded: used for order creation.
  payment?: {
    externalId: string;
    amount: number; // human-readable units, 50.00 and not 5000 cents
    currency: string; // ISO 4217
    paymentMethod: string; // normalized: "credit_card", "apple_pay", "google_pay", "paypal", ...
    paymentMethodDetails?: PaymentMethodDetails;
  };
  // payment.refunded and payment.partially_refunded.
  refund?: { amount: number; externalId?: string; reason?: string };
  // payment.failed.
  error?: { code?: string; message?: string };
  // Stored on Payment.providerData and never parsed by the core.
  providerData?: Record<string, unknown>;
}

interface NormalizedPaymentWebhookResponse extends InboundWebhookResponse {
  received: boolean;
  processed: boolean;
  event?: NormalizedPaymentEvent; // set when the webhook parsed into a payment event
}

// Invoice data a webhook can return in data.invoice. Any webhook may return it, not only
// an invoice-notify one; it is stored on Payment.providerData.
interface WebhookInvoicePayload {
  processId: string; // matches Payment.checkoutId or a provider process id
  invoiceNumber?: string;
  invoiceUrl: string;
}

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

interface AppManifest {
  name: string;
  version: string; // Semver: "1.0.0"
  integration: IntegrationConfig;
  clientSdk?: PaymentClientSdk; // how the storefront renders your payment UI, see below
  hooks?: ManifestHooks;
  health?: string; // e.g. "/health"
  eventSubscriptions?: string[]; // e.g. ["product.created", "order.updated"]
  supportedCountries?: string[]; // ISO 3166-1 alpha-2; empty = all countries
  excludedCountries?: string[]; // takes precedence over supportedCountries
  connectionFlow?: ConnectionFlow; // 'oauth' | 'api-key' | 'registration': which connect UI to render
  capabilities?: AppCapabilities; // explicit flags, overrides the endpoint-presence inference
  // Allowlist of extra endpoint paths callable through the generic
  // POST /api/apps/:installationId/call/:path proxy. Paths are relative to serviceUrl and
  // have no leading slash ("registration/submit"). Any path not listed is rejected.
  publicEndpoints?: string[];
}

// Declarative capability flags. A capability defaults to true when its endpoint exists
// (refund endpoint present means refund: true); an explicit false force-disables it.
interface AppCapabilities {
  refund?: boolean;
  openTerminal?: boolean;
  installments?: boolean; // the app can offer credit-card installments at checkout
}

type ConnectionFlow = 'oauth' | 'api-key' | 'registration';

interface PaymentClientSdk {
  renderType: 'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields'; // the default mode
  displayModes?: Array<'sdk-widget' | 'iframe' | 'redirect' | 'sandbox' | 'embedded-fields'>;
  scriptUrl?: string; // main SDK script to load
  globalName?: string; // global set by that script, the name your provider's script defines
  initMethod?: string; // default 'init'
  renderMethod?: string; // called to render the widget
  containerId?: string; // DOM element ID of the widget container
  initConfig?: Record<string, unknown>; // passed to the init method
  renderArg?: string; // argument for the render method, overrides clientSecret when set
  additionalScripts?: Array<{ url: string; optional?: boolean }>; // for example the Apple Pay SDK
  bodyStyles?: string; // CSS injected into <head> while the SDK is active
  embeddedFieldsUrl?: string; // embedded-fields: base URL the sensitive-field iframes load from
  embeddedFieldsSessionId?: string; // embedded-fields: provider session id for the iframe handshake
  embeddedFieldsProvider?: 'cardcom'; // embedded-fields: reserved. 'cardcom' is the only value the contract declares, and no payment provider sends it today
}

interface IntegrationConfig {
  type: IntegrationType;
  serviceUrl: string; // Where your service runs
  paymentContract?: { endpoints: PaymentEndpoints; oauth?: OAuthConfig };
  connectorContract?: { endpoints: ConnectorEndpoints; oauth?: OAuthConfig };
  shippingContract?: {
    endpoints: ShippingEndpoints;
    serviceType?: 'parcel' | 'on_demand'; // default 'parcel'; 'on_demand' = a live courier (no label, a time-limited quote)
    capabilities?: ShippingCapabilities; // what makes this carrier different: see "Shipping contract" below
    oauth?: OAuthConfig; // omit for an API-key carrier with no connect flow
  };
  receiptContract?: { endpoints: ReceiptEndpoints }; // optional, manifest JSON only for now: see "Receipt contract" below
  customContract?: Record<string, unknown>;
}

interface ConnectorEndpoints {
  pushProduct?: string;
  pushInventory?: string;
  pullProducts?: string;
  pullOrders?: string;
  connectionStatus?: string;
  reconcile?: string;
  deleteResource?: string;
  pushCategory?: string;
  pullCategories?: string;
  pushTag?: string;
  pullTags?: string;
  pushBrand?: string;
  pullBrands?: string;
  pushAttribute?: string;
  pullAttributes?: string;
  pushOrderNotes?: string;
  pushOrderStatus?: string;
  pushShipping?: string;
  getRefunds?: string;
  createRefund?: string;
  updateOrderFields?: string;
  pushCoupon?: string;
}

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

interface ShippingEndpoints {
  getRates?: string; // rate shopping at checkout and in the dashboard label flow
  createShipment?: string; // buys a label for a previously quoted rate
  trackShipment?: string; // polled for tracking (needed when trackingMode is 'poll' or 'both')
  voidShipment?: string; // optional: absent means "this app cannot cancel"
  createReturnShipment?: string; // optional, same terms
  validateCredentials?: string; // optional: check a credential before it is saved, no side effects
  getLabel?: string; // for labelDelivery: 'inline' apps
  listPickupPoints?: string; // optional: partner shops and lockers near the shipping address (see below)
}

interface ReceiptEndpoints {
  createDonationReceipt: string; // e.g. "/receipts/donation"
}

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

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

interface CreateDonationReceiptRequest {
  kind: 'RECEIPT' | 'REFUND';
  externalId: string; // the platform's receipt id: store it as the document's external id
  donorName: string;
  donorTaxId: string; // the donor's national ID or company number, required on a receipt
  donorEmail?: string;
  donorPhone?: string;
  sendByEmail: boolean; // the provider emails the document to the donor itself
  amount: number; // MAJOR units (180.00), not cents
  currency: string;
  description: string; // one line, e.g. "Donation: Building fund"
  language: 'he' | 'en';
  paidAt: string; // ISO 8601: when the gift was paid (or refunded)
  payment: { provider: string; reference?: string; sameProviderDealNumber?: number };
  originalDocument?: { number: number; type: string }; // kind REFUND: the receipt it reverses
}

interface CreateDonationReceiptResponse {
  documentNumber: number;
  documentType: string;
  documentUrl?: string | null;
}

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 }>;
}