Server API Reference

import {
  createServerClient,
  verifyScopedToken,
  parseSubject,
  parseContextHeader,
  recordsReadModels,
  recordsWriteModels,
  createCallbackClient,
  verifyWebhookSignature,
  ServerClientError,
} from '@foir/sdk/server';
 
import type {
  ServerClient,
  ServerClientOptions,
  GraphQLResponse,
  EditorPlacement,
  ScopedTokenClaims,
  ScopedTokenSubject,
  VerifyScopedTokenOptions,
  OperationPayload,
  CallbackClient,
  CallbackResult,
} from '@foir/sdk/server';

import { createServerClient } from '@foir/sdk/server';
 
const client = createServerClient({
  baseUrl: 'https://api.foir.dev',
  apiKey: 'sk_project_xxx',
});

interface ServerClientOptions {
  /** Base URL for the platform API (e.g., 'https://api.foir.dev'). */
  baseUrl: string;
  /** Project-scoped API key (sk_* format). */
  apiKey: string;
  /**
   * Optional. Retained for backwards compatibility with older extension
   * scaffolds that pass it; the current client ignores it.
   */
  configKey?: string;
}

interface ServerClient {
  query<T = Record<string, unknown>>(
    query: string,
    variables?: Record<string, unknown>
  ): Promise<GraphQLResponse<T>>;
}

const { data } = await client.query<{
  products: { edges: Array<{ node: { _id: string; title: string } }> };
}>(`
  query ListProducts($first: Int) {
    products(first: $first) {
      edges { node { _id title } }
    }
  }
`, { first: 100 });

await client.query(`
  mutation CreateProduct($input: CreateProductInput!) {
    createProduct(input: $input) { _id }
  }
`, {
  input: {
    naturalKey: 't-shirt',
    title: 'T-Shirt',
    price: 29.99,
  },
});

upsertRecord(modelKey: String!, naturalKey: String!, data: JSON!): UpsertRecordResult

interface EditorPlacement {
  /** 'main-editor' replaces / augments the content tab; 'sidebar' renders in the sidebar. */
  type: 'main-editor' | 'sidebar';
  /** Full URL of the editor iframe. */
  url: string;
  /** Allowed postMessage origin (defaults to url origin). */
  allowedOrigin?: string;
  /** Iframe height: 'auto' (resize via postMessage), 'fill' (100%), or fixed px. */
  height?: 'auto' | 'fill' | number;
  /** Tab label for main-editor placements (defaults to config name). */
  tabName?: string;
  /** When true, hides the standard Content tab (main-editor only). */
  hideContentTab?: boolean;
  /** Which model keys this placement applies to; omit for all models. */
  modelKeys?: string[];
}

import { verifyScopedToken } from '@foir/sdk/server';
 
const claims = await verifyScopedToken(
  token,
  'https://api.foir.dev/.well-known/jwks.json',
);

interface ScopedTokenClaims {
  iss: string;          // 'foir-platform'
  sub: string;          // pipe-delimited '<tenantId>|<projectId>|<appName>'
  cap: string[];        // capabilities, e.g. ['records:read', 'credentials:read']
  jti: string;          // unique token id
  exp: number;          // expiry (unix seconds)
  nbf: number;          // not-before (unix seconds)
  iat: number;          // issued-at (unix seconds)
  ctx?: Record<string, string>;  // operation/execution context
  rrm?: string[];       // records-read model allow-list
  rwm?: string[];       // records-write model allow-list
}

interface VerifyScopedTokenOptions {
  /**
   * Expected `iss` claim. Defaults to `'foir-platform'`. Override only
   * when verifying tokens from a non-default issuer (test harnesses,
   * alternate deploys).
   */
  expectedIssuer?: string;
}

const { tenantId, projectId, appName } = parseSubject(claims.sub);

interface ScopedTokenSubject {
  tenantId: string;
  projectId: string;
  appName: string;
}

const ctx = parseContextHeader(req.headers.get('x-foir-context'));
console.log(ctx.execution_id, ctx.triggered_by);

const readable = recordsReadModels(claims);
if (!readable.includes('product')) {
  return new Response('forbidden', { status: 403 });
}

import { Hono } from 'hono';
import {
  verifyScopedToken,
  parseSubject,
  parseContextHeader,
} from '@foir/sdk/server';
import type { ScopedTokenClaims } from '@foir/sdk/server';
 
const JWKS_URL = 'https://api.foir.dev/.well-known/jwks.json';
 
const app = new Hono<{
  Variables: { claims: ScopedTokenClaims; ctx: Record<string, string> };
}>();
 
async function verifyDispatch(c, next) {
  const token = c.req.header('x-foir-token');
  if (!token) return c.json({ error: 'missing token' }, 401);
 
  try {
    const claims = await verifyScopedToken(token, JWKS_URL);
    c.set('claims', claims);
    c.set('ctx', parseContextHeader(c.req.header('x-foir-context')));
    await next();
  } catch (err) {
    return c.json({ error: 'invalid token', detail: String(err) }, 401);
  }
}
 
app.post('/operations/*', verifyDispatch);
 
app.post('/operations/process', async (c) => {
  const claims = c.get('claims');
  const ctx = c.get('ctx');
  const { appName, projectId } = parseSubject(claims.sub);
  const payload = await c.req.json();
 
  // Use claims.cap / recordsReadModels(claims) to authorize what this
  // dispatch is allowed to do; use ctx.execution_id for callback wiring.
  return c.json({ success: true, result: { processed: true } });
});

import { createCallbackClient } from '@foir/sdk/server';
import type { OperationPayload } from '@foir/sdk/server';
 
const payload: OperationPayload = await req.json();
 
if (payload.callback && payload.executionId) {
  const cb = createCallbackClient(payload.callback, {
    executionId: payload.executionId,
    signingSecret: process.env.FOIR_SIGNING_SECRET!,
  });
 
  // Report progress as work proceeds
  await cb.progress({ pct: 25, message: 'Fetched source data' });
 
  // ... do work ...
 
  // Report success
  await cb.complete({ recordCount: 142, durationMs: 3500 });
}

interface CallbackClient<TResult = unknown> {
  complete(result: TResult): Promise<CallbackResult>;
  fail(
    code: string,
    message: string,
    opts?: { retryable?: boolean; details?: Record<string, unknown> }
  ): Promise<CallbackResult>;
  progress(update: {
    pct?: number;
    message?: string;
    metadata?: Record<string, unknown>;
  }): Promise<CallbackResult>;
  cancel(): Promise<CallbackResult>;
}
 
interface CallbackResult {
  /** Status as seen by the platform AFTER the call. */
  status: string;
  /** True when the admin cancelled the execution while the extension was working. */
  cancelled: boolean;
  /** Progress only: false when the monotonic guard rejected an out-of-order update. */
  applied?: boolean;
}

for (let i = 0; i < items.length; i++) {
  const result = await cb.progress({
    pct: Math.floor((i / items.length) * 100),
    message: `Processed ${i} of ${items.length}`,
  });
  if (result.cancelled) {
    console.log('admin cancelled, stopping work');
    return;
  }
  await processItem(items[i]);
}
await cb.complete({ processedCount: items.length });

import type { CompleteTranslateExecutionMutationVariables } from './generated';
type TranslateResult = CompleteTranslateExecutionMutationVariables['result'];
 
const cb = createCallbackClient<TranslateResult>(payload.callback!, {
  executionId: payload.executionId!,
  signingSecret: process.env.FOIR_SIGNING_SECRET!,
});

import { verifyWebhookSignature } from '@foir/sdk/server';
 
app.post('/webhooks/shopify', async (c) => {
  const body = await c.req.text();
  const signature = c.req.header('x-shopify-hmac-sha256') ?? '';
 
  const valid = await verifyWebhookSignature(
    body,
    signature,
    process.env.SHOPIFY_WEBHOOK_SECRET!,
  );
 
  if (!valid) {
    return c.text('Invalid signature', 401);
  }
 
  const payload = JSON.parse(body);
  // Process webhook...
});

interface OperationPayload {
  /** Execution id — present so the extension can include it in callbacks. */
  executionId?: string;
 
  /** Unique key identifying this operation. */
  operationKey: string;
 
  /** How this operation was triggered. */
  trigger: OperationTrigger;
 
  /** Input data provided by the caller. */
  input: Record<string, unknown>;
 
  /** Content/field value (for field-triggered operations). */
  content: unknown;
 
  /** Record context, if the operation was triggered from a record. */
  record: OperationRecordContext | null;
 
  /** Platform context (tenant, project, user, locale). */
  context: OperationContext;
 
  /** App credentials, auto-injected by the platform. */
  credentials?: Record<string, unknown>;
 
  /** App config, auto-injected by the platform. */
  config?: Record<string, unknown>;
 
  /** Async-callback dispatch metadata. Present iff dispatched in 'async' mode. */
  callback?: OperationCallback;
}
 
interface OperationTrigger {
  type: 'ui' | 'api' | 'lifecycle' | 'field';
  fieldKey?: string;
  fieldType?: string;
}
 
interface OperationRecordContext {
  id: string;
  modelKey: string;
  versionId?: string;
  data: Record<string, unknown>;
  metadata: { naturalKey?: string; [key: string]: unknown };
}
 
interface OperationContext {
  tenantId: string;
  projectId: string;
  userId?: string;
  customerId?: string;
  locale?: string;
  timestamp: string;
}
 
interface OperationCallback {
  gqlEndpoint: string;
  token: string;            // scoped Bearer token
  expiresAt: string;        // RFC3339
  mutations: {
    complete: string;       // e.g. 'completeTranslateExecution'
    fail: string;
    progress: string;
    cancel: string;
  };
}

interface OperationResult {
  success: boolean;
  result?: unknown;
  error?: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
  metadata?: Record<string, unknown>;
}

return c.json({
  success: true,
  result: { redirectCount: 42 },
  metadata: { durationMs: 1200 },
});

return c.json({
  success: false,
  error: {
    code: 'MISSING_CREDENTIALS',
    message: 'Cloudflare API token is not configured',
  },
});

class ServerClientError extends Error {
  status?: number;
  response?: unknown;
}

- import { verifyAndParseOperation } from '@foir/sdk/server';
+ import { verifyScopedToken, parseSubject } from '@foir/sdk/server';
 
  app.post('/operations/process', async (c) => {
-   const body = await c.req.text();
-   const signature = c.req.header('x-foir-signature');
-   const payload = await verifyAndParseOperation(body, signature, {
-     webhookSecret: process.env.WEBHOOK_SECRET!,
-   });
+   const token = c.req.header('x-foir-token');
+   if (!token) return c.json({ error: 'missing token' }, 401);
+   const claims = await verifyScopedToken(
+     token,
+     'https://api.foir.dev/.well-known/jwks.json',
+   );
+   const payload = await c.req.json();
+   const { appName } = parseSubject(claims.sub);
    // ...
  });