@godxjp/server-sdk 0.1.0

package/dist/org.d.ts

@@ -0,0 +1,126 @@
+import { GodxHttpError } from './http.js';
+import 'jose';
+
+/**
+ * ./org — typed client for the Delegated Organization API (`/api/org/v1/*`),
+ * the platform's write-back surface: the ONLY sanctioned way a service changes
+ * platform-owned directory data. The identity feed then carries the change to
+ * every consumer (the feed itself is one-way; see ./sync).
+ *
+ * Auth model, exactly as the platform enforces it (routes/api/org.php):
+ * - Bearer access token minted FOR the `organization-api` recipient resource
+ *   (`aud` contains `{issuer}/api/org/v1`) by a `user`-lane principal.
+ * - Tenancy is the token's organization, re-derived server-side per request —
+ *   this client never sends an organization id.
+ * - Each route needs its `org.{resource}:{read|write}` scope; a missing scope
+ *   answers 403 `insufficient_scope` with a WWW-Authenticate header (RFC 6750),
+ *   which this client surfaces verbatim.
+ *
+ * NOTE (2026-09): the platform grants that audience on the MINI-APP lane only
+ * (`TokenIssuer::miniAppResourceAudiences`). A downstream service-launch token
+ * does not carry it yet — godx-jp/id has the proposal to widen that lane.
+ *
+ * International-standard behaviours built in:
+ * - `Idempotency-Key` (IETF draft-ietf-httpapi-idempotency-key-header) is sent
+ *   on every write — generated when not supplied. The org/v1 surface does not
+ *   *honor* it yet (the admin surface does); sending it is forward-compatible
+ *   and costs nothing.
+ * - 401/403 surface the `WWW-Authenticate` challenge; 429 surfaces
+ *   `Retry-After`; validation errors (422) surface the per-field messages.
+ * - Page-based pagination is wrapped in an async iterator so callers cannot
+ *   forget page 2.
+ */
+
+interface OrgApiConfig {
+    issuer: string;
+    /** Bearer access token whose aud includes {issuer}/api/org/v1. */
+    accessToken: string;
+}
+interface PageMeta {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+}
+interface Page<T> {
+    data: T[];
+    meta: PageMeta;
+}
+interface OrgEmployee {
+    id: string;
+    employee_code: string;
+    full_name: string;
+    email?: string | null;
+    department_id?: string | null;
+    branch_id?: string | null;
+    user_id?: string | null;
+    [key: string]: unknown;
+}
+interface OrgDepartment {
+    id: string;
+    code?: string | null;
+    name: string;
+    [key: string]: unknown;
+}
+interface OrgBranch {
+    id: string;
+    code?: string | null;
+    name: string;
+    [key: string]: unknown;
+}
+interface OrgTeam {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+interface OrgMe {
+    [key: string]: unknown;
+}
+declare class OrgApiError extends GodxHttpError {
+    /** RFC 6750 challenge, when the platform sent one (401/403). */
+    readonly wwwAuthenticate: string | null;
+    /** Seconds to wait, when the platform answered 429 with Retry-After. */
+    readonly retryAfterSeconds: number | null;
+    /** Laravel validation messages per field, when the answer was 422. */
+    readonly validationErrors: Record<string, string[]> | null;
+    constructor(status: number, body: string, message: string, headers: Headers);
+}
+declare function createOrgApi(config: OrgApiConfig): {
+    /** GET /me — scope org:profile. */
+    me: () => Promise<OrgMe>;
+    employees: {
+        list: (page?: number) => Promise<Page<OrgEmployee>>;
+        all: () => AsyncGenerator<OrgEmployee, void, void>;
+        /** scope org.employees:write */
+        create: (payload: Record<string, unknown>, idempotencyKey?: string) => Promise<{
+            data: OrgEmployee;
+        }>;
+        /** Who this user reports to — rides org.employees:read. */
+        managerOf: (consoleUserId: string) => Promise<{
+            data: unknown;
+        }>;
+    };
+    departments: {
+        list: (page?: number) => Promise<Page<OrgDepartment>>;
+        all: () => AsyncGenerator<OrgDepartment, void, void>;
+        create: (payload: Record<string, unknown>, idempotencyKey?: string) => Promise<{
+            data: OrgDepartment;
+        }>;
+    };
+    branches: {
+        list: (page?: number) => Promise<Page<OrgBranch>>;
+        all: () => AsyncGenerator<OrgBranch, void, void>;
+        create: (payload: Record<string, unknown>, idempotencyKey?: string) => Promise<{
+            data: OrgBranch;
+        }>;
+    };
+    teams: {
+        list: (page?: number) => Promise<Page<OrgTeam>>;
+        all: () => AsyncGenerator<OrgTeam, void, void>;
+        create: (payload: Record<string, unknown>, idempotencyKey?: string) => Promise<{
+            data: OrgTeam;
+        }>;
+    };
+};
+
+export { type OrgApiConfig, OrgApiError, type OrgBranch, type OrgDepartment, type OrgEmployee, type OrgMe, type OrgTeam, type Page, type PageMeta, createOrgApi };

package/dist/org.js

@@ -0,0 +1,101 @@
+import {
+  GodxHttpError
+} from "./chunk-DMXYEWYY.js";
+
+// src/org.ts
+var OrgApiError = class extends GodxHttpError {
+  /** RFC 6750 challenge, when the platform sent one (401/403). */
+  wwwAuthenticate;
+  /** Seconds to wait, when the platform answered 429 with Retry-After. */
+  retryAfterSeconds;
+  /** Laravel validation messages per field, when the answer was 422. */
+  validationErrors;
+  constructor(status, body, message, headers) {
+    super(status, body, message);
+    this.name = "OrgApiError";
+    this.wwwAuthenticate = headers.get("WWW-Authenticate");
+    const retryAfter = headers.get("Retry-After");
+    this.retryAfterSeconds = retryAfter !== null && /^\d+$/.test(retryAfter) ? Number(retryAfter) : null;
+    let validation = null;
+    try {
+      const parsed = JSON.parse(body);
+      if (parsed && typeof parsed === "object" && parsed.errors) validation = parsed.errors;
+    } catch {
+    }
+    this.validationErrors = validation;
+  }
+};
+async function unwrap(response, what) {
+  if (!response.ok) {
+    const body = await response.text();
+    const challenge = response.headers.get("WWW-Authenticate");
+    const hint = response.status === 401 ? `the token is missing, expired, or was not minted for the organization-api audience${challenge ? ` \u2014 ${challenge}` : ""}` : response.status === 403 ? `the token lacks the route's org.* scope${challenge ? ` \u2014 ${challenge}` : ""}` : response.status === 422 ? "validation refused the payload (see validationErrors)" : response.status === 429 ? "rate limited \u2014 honor retryAfterSeconds" : "see the response body";
+    throw new OrgApiError(response.status, body, `${what} answered ${response.status}: ${hint}`, response.headers);
+  }
+  return await response.json();
+}
+function createOrgApi(config) {
+  const base = config.issuer.replace(/\/$/, "") + "/api/org/v1";
+  const get = async (path, query) => {
+    const url = new URL(base + path);
+    if (query) url.search = new URLSearchParams(query).toString();
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${config.accessToken}`, Accept: "application/json" }
+    });
+    return unwrap(response, `GET ${path}`);
+  };
+  const post = async (path, payload, idempotencyKey) => {
+    const response = await fetch(base + path, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.accessToken}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "Idempotency-Key": idempotencyKey ?? crypto.randomUUID()
+      },
+      body: JSON.stringify(payload)
+    });
+    return unwrap(response, `POST ${path}`);
+  };
+  async function* paginate(path) {
+    let page = 1;
+    for (; ; ) {
+      const result = await get(path, { page: String(page) });
+      for (const row of result.data) yield row;
+      if (result.meta.current_page >= result.meta.last_page) return;
+      page = result.meta.current_page + 1;
+    }
+  }
+  return {
+    /** GET /me — scope org:profile. */
+    me: () => get("/me"),
+    employees: {
+      list: (page) => get("/employees", page ? { page: String(page) } : void 0),
+      all: () => paginate("/employees"),
+      /** scope org.employees:write */
+      create: (payload, idempotencyKey) => post("/employees", payload, idempotencyKey),
+      /** Who this user reports to — rides org.employees:read. */
+      managerOf: (consoleUserId) => get(`/users/${encodeURIComponent(consoleUserId)}/manager`)
+    },
+    departments: {
+      list: (page) => get("/departments", page ? { page: String(page) } : void 0),
+      all: () => paginate("/departments"),
+      create: (payload, idempotencyKey) => post("/departments", payload, idempotencyKey)
+    },
+    branches: {
+      list: (page) => get("/branches", page ? { page: String(page) } : void 0),
+      all: () => paginate("/branches"),
+      create: (payload, idempotencyKey) => post("/branches", payload, idempotencyKey)
+    },
+    teams: {
+      list: (page) => get("/teams", page ? { page: String(page) } : void 0),
+      all: () => paginate("/teams"),
+      create: (payload, idempotencyKey) => post("/teams", payload, idempotencyKey)
+    }
+  };
+}
+export {
+  OrgApiError,
+  createOrgApi
+};
+//# sourceMappingURL=org.js.map

package/dist/org.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/org.ts"],"sourcesContent":["/**\n * ./org — typed client for the Delegated Organization API (`/api/org/v1/*`),\n * the platform's write-back surface: the ONLY sanctioned way a service changes\n * platform-owned directory data. The identity feed then carries the change to\n * every consumer (the feed itself is one-way; see ./sync).\n *\n * Auth model, exactly as the platform enforces it (routes/api/org.php):\n * - Bearer access token minted FOR the `organization-api` recipient resource\n *   (`aud` contains `{issuer}/api/org/v1`) by a `user`-lane principal.\n * - Tenancy is the token's organization, re-derived server-side per request —\n *   this client never sends an organization id.\n * - Each route needs its `org.{resource}:{read|write}` scope; a missing scope\n *   answers 403 `insufficient_scope` with a WWW-Authenticate header (RFC 6750),\n *   which this client surfaces verbatim.\n *\n * NOTE (2026-09): the platform grants that audience on the MINI-APP lane only\n * (`TokenIssuer::miniAppResourceAudiences`). A downstream service-launch token\n * does not carry it yet — godx-jp/id has the proposal to widen that lane.\n *\n * International-standard behaviours built in:\n * - `Idempotency-Key` (IETF draft-ietf-httpapi-idempotency-key-header) is sent\n *   on every write — generated when not supplied. The org/v1 surface does not\n *   *honor* it yet (the admin surface does); sending it is forward-compatible\n *   and costs nothing.\n * - 401/403 surface the `WWW-Authenticate` challenge; 429 surfaces\n *   `Retry-After`; validation errors (422) surface the per-field messages.\n * - Page-based pagination is wrapped in an async iterator so callers cannot\n *   forget page 2.\n */\nimport { GodxHttpError } from \"./http\";\n\nexport interface OrgApiConfig {\n  issuer: string;\n  /** Bearer access token whose aud includes {issuer}/api/org/v1. */\n  accessToken: string;\n}\n\nexport interface PageMeta {\n  current_page: number;\n  last_page: number;\n  per_page: number;\n  total: number;\n}\n\nexport interface Page<T> {\n  data: T[];\n  meta: PageMeta;\n}\n\nexport interface OrgEmployee {\n  id: string;\n  employee_code: string;\n  full_name: string;\n  email?: string | null;\n  department_id?: string | null;\n  branch_id?: string | null;\n  user_id?: string | null;\n  [key: string]: unknown;\n}\n\nexport interface OrgDepartment {\n  id: string;\n  code?: string | null;\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface OrgBranch {\n  id: string;\n  code?: string | null;\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface OrgTeam {\n  id: string;\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface OrgMe {\n  [key: string]: unknown;\n}\n\nexport class OrgApiError extends GodxHttpError {\n  /** RFC 6750 challenge, when the platform sent one (401/403). */\n  readonly wwwAuthenticate: string | null;\n  /** Seconds to wait, when the platform answered 429 with Retry-After. */\n  readonly retryAfterSeconds: number | null;\n  /** Laravel validation messages per field, when the answer was 422. */\n  readonly validationErrors: Record<string, string[]> | null;\n\n  constructor(status: number, body: string, message: string, headers: Headers) {\n    super(status, body, message);\n    this.name = \"OrgApiError\";\n    this.wwwAuthenticate = headers.get(\"WWW-Authenticate\");\n    const retryAfter = headers.get(\"Retry-After\");\n    this.retryAfterSeconds = retryAfter !== null && /^\\d+$/.test(retryAfter) ? Number(retryAfter) : null;\n    let validation: Record<string, string[]> | null = null;\n    try {\n      const parsed = JSON.parse(body) as { errors?: Record<string, string[]> };\n      if (parsed && typeof parsed === \"object\" && parsed.errors) validation = parsed.errors;\n    } catch {\n      /* body was not JSON — nothing more to surface */\n    }\n    this.validationErrors = validation;\n  }\n}\n\nasync function unwrap<T>(response: Response, what: string): Promise<T> {\n  if (!response.ok) {\n    const body = await response.text();\n    const challenge = response.headers.get(\"WWW-Authenticate\");\n    const hint =\n      response.status === 401\n        ? `the token is missing, expired, or was not minted for the organization-api audience${challenge ? ` — ${challenge}` : \"\"}`\n        : response.status === 403\n          ? `the token lacks the route's org.* scope${challenge ? ` — ${challenge}` : \"\"}`\n          : response.status === 422\n            ? \"validation refused the payload (see validationErrors)\"\n            : response.status === 429\n              ? \"rate limited — honor retryAfterSeconds\"\n              : \"see the response body\";\n    throw new OrgApiError(response.status, body, `${what} answered ${response.status}: ${hint}`, response.headers);\n  }\n  return (await response.json()) as T;\n}\n\nexport function createOrgApi(config: OrgApiConfig) {\n  const base = config.issuer.replace(/\\/$/, \"\") + \"/api/org/v1\";\n\n  const get = async <T>(path: string, query?: Record<string, string>): Promise<T> => {\n    const url = new URL(base + path);\n    if (query) url.search = new URLSearchParams(query).toString();\n    const response = await fetch(url, {\n      headers: { Authorization: `Bearer ${config.accessToken}`, Accept: \"application/json\" },\n    });\n    return unwrap<T>(response, `GET ${path}`);\n  };\n\n  const post = async <T>(path: string, payload: Record<string, unknown>, idempotencyKey?: string): Promise<T> => {\n    const response = await fetch(base + path, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${config.accessToken}`,\n        Accept: \"application/json\",\n        \"Content-Type\": \"application/json\",\n        \"Idempotency-Key\": idempotencyKey ?? crypto.randomUUID(),\n      },\n      body: JSON.stringify(payload),\n    });\n    return unwrap<T>(response, `POST ${path}`);\n  };\n\n  /** Follow page-based pagination to the end, yielding every row once. */\n  async function* paginate<T>(path: string): AsyncGenerator<T, void, void> {\n    let page = 1;\n    for (;;) {\n      const result = await get<Page<T>>(path, { page: String(page) });\n      for (const row of result.data) yield row;\n      if (result.meta.current_page >= result.meta.last_page) return;\n      page = result.meta.current_page + 1;\n    }\n  }\n\n  return {\n    /** GET /me — scope org:profile. */\n    me: () => get<OrgMe>(\"/me\"),\n\n    employees: {\n      list: (page?: number) => get<Page<OrgEmployee>>(\"/employees\", page ? { page: String(page) } : undefined),\n      all: () => paginate<OrgEmployee>(\"/employees\"),\n      /** scope org.employees:write */\n      create: (payload: Record<string, unknown>, idempotencyKey?: string) =>\n        post<{ data: OrgEmployee }>(\"/employees\", payload, idempotencyKey),\n      /** Who this user reports to — rides org.employees:read. */\n      managerOf: (consoleUserId: string) => get<{ data: unknown }>(`/users/${encodeURIComponent(consoleUserId)}/manager`),\n    },\n\n    departments: {\n      list: (page?: number) => get<Page<OrgDepartment>>(\"/departments\", page ? { page: String(page) } : undefined),\n      all: () => paginate<OrgDepartment>(\"/departments\"),\n      create: (payload: Record<string, unknown>, idempotencyKey?: string) =>\n        post<{ data: OrgDepartment }>(\"/departments\", payload, idempotencyKey),\n    },\n\n    branches: {\n      list: (page?: number) => get<Page<OrgBranch>>(\"/branches\", page ? { page: String(page) } : undefined),\n      all: () => paginate<OrgBranch>(\"/branches\"),\n      create: (payload: Record<string, unknown>, idempotencyKey?: string) =>\n        post<{ data: OrgBranch }>(\"/branches\", payload, idempotencyKey),\n    },\n\n    teams: {\n      list: (page?: number) => get<Page<OrgTeam>>(\"/teams\", page ? { page: String(page) } : undefined),\n      all: () => paginate<OrgTeam>(\"/teams\"),\n      create: (payload: Record<string, unknown>, idempotencyKey?: string) =>\n        post<{ data: OrgTeam }>(\"/teams\", payload, idempotencyKey),\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/sync.d.ts

@@ -0,0 +1,174 @@
+type IdentityFamily = "organization" | "brand" | "branch" | "user" | "employee" | "service_user_access" | "org_service_role" | "role_assignment";
+declare const KNOWN_CONTRACT_VERSIONS: readonly ["v1", "v2"];
+/** CloudEvents 1.0 envelope as the relay publishes it (contract §4). */
+interface IdentityEnvelope {
+    specversion: "1.0";
+    /** UUIDv4 — THE idempotency key (same across multi-tenant fan-out copies). */
+    id: string;
+    /** Platform origin — pin per environment and verify. */
+    source: string;
+    /** jp.godx.identity.{family}.{action} */
+    type: string;
+    /** {family}/{id-the-consumer-holds} — exactly one "/", both halves filled. */
+    subject: string;
+    time: string;
+    datacontenttype: "application/json";
+    /** Globally monotonic ordering fence (identity_outbox.sequence). */
+    sequence: number;
+    data: Record<string, unknown>;
+}
+interface ParsedSubject {
+    family: IdentityFamily | (string & {});
+    id: string;
+}
+declare class SyncContractError extends Error {
+    constructor(message: string);
+}
+/** Split a CloudEvents/snapshot `subject`. Rejects anything the contract rejects. */
+declare function parseSubject(subject: string): ParsedSubject;
+/** Validate a raw payload into an IdentityEnvelope, with expected-vs-actual errors. */
+declare function parseEnvelope(raw: unknown, opts?: {
+    expectedSource?: string;
+}): IdentityEnvelope;
+/**
+ * What a consumer implements to hold a projection — one code path for
+ * snapshot rows and stream events, exactly as the contract intends
+ * ("rows[].subject is byte-identical to the CloudEvents subject").
+ */
+interface Projector {
+    /** Upsert the full mirrored payload for this subject (data is never a diff). */
+    apply(subject: ParsedSubject, data: Record<string, unknown>, context: ProjectorContext): Promise<void>;
+}
+interface ProjectorContext {
+    organizationId: string;
+    /** The watermark this row is consistent up to. */
+    sequence: number;
+}
+/** The stream-leg seam (JetStream durable on a Node host). Not implemented here yet. */
+interface Transport {
+    pull(handler: (envelope: IdentityEnvelope) => Promise<void>): Promise<void>;
+}
+/** Dedupe seam keyed on the CloudEvents id — the consumer's job, per contract §4. */
+interface Inbox {
+    /** true when this id was already applied — skip it. */
+    seen(eventId: string): Promise<boolean>;
+    record(eventId: string, sequence: number): Promise<void>;
+}
+/**
+ * Which (source, organization) pairs this consumer accepts — php-sdk's
+ * TenantPolicy. Deny is a `terminated` outcome, never an exception: an event
+ * for a tenant that is not yours is noise, not an incident.
+ */
+interface TenantPolicy {
+    allows(source: string, organizationId: string | null): boolean;
+}
+declare const acceptTenants: (source: string, organizationIds: readonly string[]) => TenantPolicy;
+/**
+ * What happened to one delivery — mirrors php-sdk's Outcome and the contract's
+ * nak-vs-term rule. The HTTP mapping (see handleIngestRequest) is:
+ * applied/skipped_* → 2xx (ack) · retry → 5xx (nak, redeliver) ·
+ * terminated → 200 with the outcome named (term: redelivery cannot help).
+ */
+type Outcome = "applied" | "skipped_duplicate" | "skipped_stale" | "terminated_unknown_type" | "terminated_tenant_refused" | "retry";
+interface Delivery {
+    outcome: Outcome;
+    eventId: string;
+    /** Present on terminated/retry — the human-readable why. */
+    reason?: string;
+}
+/**
+ * The one pipeline both legs feed: validate → dedupe → tenant gate → project
+ * → record. A snapshot pass uses the Projector directly; every EVENT goes
+ * through here.
+ */
+declare function createProcessor(deps: {
+    projector: Projector;
+    inbox: Inbox;
+    tenantPolicy?: TenantPolicy;
+    /** Families this consumer mirrors; events for others are terminated (contract §3 nak-vs-term). */
+    families?: readonly IdentityFamily[];
+}): (envelope: IdentityEnvelope) => Promise<Delivery>;
+/** Structural subset of D1Database, so this module has no CF type dependency. */
+interface D1Like {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            first<T = unknown>(): Promise<T | null>;
+            run(): Promise<unknown>;
+        };
+    };
+}
+/** DDL for the inbox table — copy into a migration verbatim. */
+declare const D1_INBOX_DDL = "CREATE TABLE IF NOT EXISTS godx_sync_inbox (\n  event_id TEXT PRIMARY KEY,\n  sequence INTEGER NOT NULL,\n  applied_at INTEGER NOT NULL\n);";
+declare function createD1Inbox(db: D1Like, table?: string): Inbox;
+/** Produce Standard Webhooks headers for a payload — the bridge's half. */
+declare function signWebhook(secret: string, body: string, opts?: {
+    id?: string;
+    timestamp?: number;
+}): Promise<{
+    "webhook-id": string;
+    "webhook-timestamp": string;
+    "webhook-signature": string;
+}>;
+/**
+ * Verify Standard Webhooks headers. Returns null when valid, otherwise the
+ * human-readable refusal (never throws on bad input).
+ */
+declare function verifyWebhook(secret: string, body: string, headers: {
+    get(name: string): string | null;
+}): Promise<string | null>;
+interface IngestResult {
+    deliveries: Delivery[];
+    response: Response;
+}
+/**
+ * Handle one CloudEvents-over-HTTP delivery. Pure fetch API — mount it from
+ * any framework in one line. HTTP mapping of outcomes:
+ *   every outcome except retry → 200 (ack; body lists per-event outcomes)
+ *   any retry                  → 500 (nak: the sender must redeliver)
+ *   bad signature              → 401 · wrong content type → 415 · bad JSON/envelope → 400 (term)
+ */
+declare function handleIngestRequest(request: Request, deps: {
+    secret: string;
+    process: (envelope: IdentityEnvelope) => Promise<Delivery>;
+    expectedSource?: string;
+}): Promise<Response>;
+interface SnapshotRow {
+    subject: string;
+    data: Record<string, unknown>;
+}
+interface SnapshotPage {
+    contractVersion: string;
+    family: string;
+    organizationId: string;
+    /** Watermark: resume the stream from here AFTER the pass completes. */
+    sequence: number;
+    rows: SnapshotRow[];
+    nextCursor: string | null;
+}
+interface ReconcileResult {
+    organizationId: string;
+    /** The highest watermark of the pass — hand this to the stream leg. */
+    sequence: number;
+    pages: number;
+    rows: number;
+}
+/**
+ * GET /api/sso/service/snapshot/{family} — cursor-paged keyset read of current
+ * state (NOT a replay of history). Auth is the service credential; tenancy is
+ * the credential's, never a parameter.
+ */
+declare function createSnapshotClient(config: {
+    issuer: string;
+    serviceSlug: string;
+    serviceSecret: string;
+}): {
+    fetchPage: (family: IdentityFamily, opts?: {
+        cursor?: string;
+        limit?: number;
+    }) => Promise<SnapshotPage>;
+    reconcile: (family: IdentityFamily, projector: Projector, opts?: {
+        limit?: number;
+    }) => Promise<ReconcileResult>;
+};
+
+export { D1_INBOX_DDL, type Delivery, type IdentityEnvelope, type IdentityFamily, type Inbox, type IngestResult, KNOWN_CONTRACT_VERSIONS, type Outcome, type ParsedSubject, type Projector, type ProjectorContext, type ReconcileResult, type SnapshotPage, type SnapshotRow, SyncContractError, type TenantPolicy, type Transport, acceptTenants, createD1Inbox, createProcessor, createSnapshotClient, handleIngestRequest, parseEnvelope, parseSubject, signWebhook, verifyWebhook };

package/dist/sync.js

@@ -0,0 +1,241 @@
+import {
+  GodxHttpError
+} from "./chunk-DMXYEWYY.js";
+
+// src/sync.ts
+var KNOWN_CONTRACT_VERSIONS = ["v1", "v2"];
+var SyncContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SyncContractError";
+  }
+};
+function parseSubject(subject) {
+  const parts = subject.split("/");
+  if (parts.length !== 2 || parts[0] === "" || parts[1] === "") {
+    throw new SyncContractError(
+      `identity feed subject "${subject}" is not "{family}/{id}" \u2014 exactly one "/" with both halves filled.`
+    );
+  }
+  return { family: parts[0], id: parts[1] };
+}
+function parseEnvelope(raw, opts) {
+  const e = raw;
+  if (!e || typeof e !== "object") throw new SyncContractError("envelope is not an object");
+  if (e.specversion !== "1.0") {
+    throw new SyncContractError(`envelope specversion is ${JSON.stringify(e.specversion)}, expected "1.0" \u2014 rejected outright, as the php-sdk does.`);
+  }
+  if (typeof e.id !== "string" || e.id === "") throw new SyncContractError("envelope has no CloudEvents id (the idempotency key)");
+  if (typeof e.type !== "string" || !e.type.startsWith("jp.godx.identity.")) {
+    throw new SyncContractError(`envelope type ${JSON.stringify(e.type)} does not start with "jp.godx.identity."`);
+  }
+  if (typeof e.sequence !== "number") throw new SyncContractError("envelope has no numeric sequence (the ordering fence)");
+  if (typeof e.subject !== "string") throw new SyncContractError("envelope has no subject");
+  parseSubject(e.subject);
+  if (opts?.expectedSource !== void 0 && e.source !== opts.expectedSource) {
+    throw new SyncContractError(
+      `envelope source is ${JSON.stringify(e.source)}, expected ${JSON.stringify(opts.expectedSource)} \u2014 pin the platform origin per environment.`
+    );
+  }
+  return e;
+}
+var acceptTenants = (source, organizationIds) => ({
+  allows: (s, org) => s === source && (org === null || organizationIds.includes(org))
+});
+function createProcessor(deps) {
+  return async (envelope) => {
+    const { id } = envelope;
+    let subject;
+    try {
+      subject = parseSubject(envelope.subject);
+    } catch (e) {
+      return { outcome: "terminated_unknown_type", eventId: id, reason: e.message };
+    }
+    if (deps.families && !deps.families.includes(subject.family)) {
+      return {
+        outcome: "terminated_unknown_type",
+        eventId: id,
+        reason: `family "${subject.family}" is not mirrored here (mirrored: ${deps.families.join(", ")})`
+      };
+    }
+    const organizationId = typeof envelope.data["console_organization_id"] === "string" ? envelope.data["console_organization_id"] : null;
+    if (deps.tenantPolicy && !deps.tenantPolicy.allows(envelope.source, organizationId)) {
+      return {
+        outcome: "terminated_tenant_refused",
+        eventId: id,
+        reason: `source=${envelope.source} organization=${organizationId ?? "(none)"} is not accepted by this consumer's tenant policy`
+      };
+    }
+    if (await deps.inbox.seen(id)) {
+      return { outcome: "skipped_duplicate", eventId: id };
+    }
+    try {
+      await deps.projector.apply(subject, envelope.data, {
+        organizationId: organizationId ?? "",
+        sequence: envelope.sequence
+      });
+      await deps.inbox.record(id, envelope.sequence);
+      return { outcome: "applied", eventId: id };
+    } catch (e) {
+      return { outcome: "retry", eventId: id, reason: e instanceof Error ? e.message : String(e) };
+    }
+  };
+}
+var D1_INBOX_DDL = `CREATE TABLE IF NOT EXISTS godx_sync_inbox (
+  event_id TEXT PRIMARY KEY,
+  sequence INTEGER NOT NULL,
+  applied_at INTEGER NOT NULL
+);`;
+function createD1Inbox(db, table = "godx_sync_inbox") {
+  return {
+    async seen(eventId) {
+      const row = await db.prepare(`SELECT 1 AS x FROM ${table} WHERE event_id = ?`).bind(eventId).first();
+      return row !== null;
+    },
+    async record(eventId, sequence) {
+      await db.prepare(`INSERT OR IGNORE INTO ${table} (event_id, sequence, applied_at) VALUES (?, ?, ?)`).bind(eventId, sequence, Date.now()).run();
+    }
+  };
+}
+var WEBHOOK_TOLERANCE_SECONDS = 5 * 60;
+async function hmacKey(secret) {
+  const raw = secret.startsWith("whsec_") ? Uint8Array.from(atob(secret.slice(6)), (ch) => ch.charCodeAt(0)) : new TextEncoder().encode(secret);
+  return crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify"
+  ]);
+}
+async function signWebhook(secret, body, opts) {
+  const id = opts?.id ?? crypto.randomUUID();
+  const timestamp = String(opts?.timestamp ?? Math.floor(Date.now() / 1e3));
+  const key = await hmacKey(secret);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${id}.${timestamp}.${body}`));
+  const signature = `v1,${btoa(String.fromCharCode(...new Uint8Array(mac)))}`;
+  return { "webhook-id": id, "webhook-timestamp": timestamp, "webhook-signature": signature };
+}
+async function verifyWebhook(secret, body, headers) {
+  const id = headers.get("webhook-id");
+  const timestamp = headers.get("webhook-timestamp");
+  const signatureHeader = headers.get("webhook-signature");
+  if (!id || !timestamp || !signatureHeader) {
+    return "missing webhook-id / webhook-timestamp / webhook-signature header (Standard Webhooks)";
+  }
+  const age = Math.abs(Math.floor(Date.now() / 1e3) - Number(timestamp));
+  if (!Number.isFinite(age) || age > WEBHOOK_TOLERANCE_SECONDS) {
+    return `webhook-timestamp is ${timestamp} \u2014 outside the \xB1${WEBHOOK_TOLERANCE_SECONDS}s tolerance (replay guard)`;
+  }
+  const key = await hmacKey(secret);
+  const expected = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+  for (const part of signatureHeader.split(" ")) {
+    const [version, value] = part.split(",", 2);
+    if (version !== "v1" || !value) continue;
+    let mac;
+    try {
+      mac = Uint8Array.from(atob(value), (ch) => ch.charCodeAt(0));
+    } catch {
+      continue;
+    }
+    if (await crypto.subtle.verify("HMAC", key, mac, expected)) return null;
+  }
+  return "no webhook-signature entry matched (wrong secret, or the body was altered in transit)";
+}
+async function handleIngestRequest(request, deps) {
+  const json = (status, body2) => new Response(JSON.stringify(body2), { status, headers: { "Content-Type": "application/json" } });
+  if (request.method !== "POST") return json(405, { error: "POST only" });
+  const contentType = (request.headers.get("Content-Type") ?? "").split(";")[0].trim();
+  const batch = contentType === "application/cloudevents-batch+json";
+  if (!batch && contentType !== "application/cloudevents+json") {
+    return json(415, {
+      error: `Content-Type "${contentType}" is not a CloudEvents structured mode \u2014 send application/cloudevents+json (one event) or application/cloudevents-batch+json (array).`
+    });
+  }
+  const body = await request.text();
+  const refusal = await verifyWebhook(deps.secret, body, request.headers);
+  if (refusal !== null) return json(401, { error: refusal });
+  let envelopes;
+  try {
+    const parsed = JSON.parse(body);
+    const raw = batch ? parsed : [parsed];
+    if (!Array.isArray(raw)) throw new SyncContractError("batch content-type but the body is not an array");
+    envelopes = raw.map((e) => parseEnvelope(e, { expectedSource: deps.expectedSource }));
+  } catch (e) {
+    return json(400, { error: e instanceof Error ? e.message : String(e) });
+  }
+  const deliveries = [];
+  for (const envelope of envelopes) {
+    deliveries.push(await deps.process(envelope));
+  }
+  const mustRetry = deliveries.some((d) => d.outcome === "retry");
+  return json(mustRetry ? 500 : 200, { deliveries });
+}
+function createSnapshotClient(config) {
+  const fetchPage = async (family, opts) => {
+    const url = new URL(`/api/sso/service/snapshot/${family}`, config.issuer);
+    if (opts?.cursor) url.searchParams.set("cursor", opts.cursor);
+    if (opts?.limit) url.searchParams.set("limit", String(opts.limit));
+    const res = await fetch(url, {
+      headers: {
+        "X-Service-Slug": config.serviceSlug,
+        "X-Service-Secret": config.serviceSecret,
+        Accept: "application/json"
+      }
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      const hint = res.status === 410 ? "the cursor's watermark aged out of the stream \u2014 restart the pass from the beginning (no cursor)." : res.status === 400 ? "the cursor is malformed or belongs to another family \u2014 cursors are opaque, echo next_cursor verbatim." : res.status === 403 ? "the credential lacks service_api_enabled, or the family is not snapshot-able for it." : "check X-Service-Slug/X-Service-Secret and the platform logs (X-Request-Id).";
+      throw new GodxHttpError(res.status, body, `identity snapshot ${family} answered ${res.status} \u2014 ${hint}`);
+    }
+    const b = await res.json();
+    if (!KNOWN_CONTRACT_VERSIONS.includes(b.contract_version)) {
+      throw new SyncContractError(
+        `snapshot answered contract_version ${JSON.stringify(b.contract_version)}; this SDK knows ${KNOWN_CONTRACT_VERSIONS.join(", ")} \u2014 a consumer that does not recognise it must stop, not guess.`
+      );
+    }
+    return {
+      contractVersion: b.contract_version,
+      family: b.family,
+      organizationId: b.organization_id,
+      sequence: b.sequence,
+      rows: b.rows ?? [],
+      nextCursor: b.next_cursor ?? null
+    };
+  };
+  const reconcile = async (family, projector, opts) => {
+    let cursor;
+    let pages = 0;
+    let rows = 0;
+    let sequence = 0;
+    let organizationId = "";
+    do {
+      const page = await fetchPage(family, { cursor, limit: opts?.limit });
+      pages++;
+      sequence = Math.max(sequence, page.sequence);
+      organizationId = page.organizationId;
+      for (const row of page.rows) {
+        await projector.apply(parseSubject(row.subject), row.data, {
+          organizationId: page.organizationId,
+          sequence: page.sequence
+        });
+        rows++;
+      }
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor !== void 0);
+    return { organizationId, sequence, pages, rows };
+  };
+  return { fetchPage, reconcile };
+}
+export {
+  D1_INBOX_DDL,
+  KNOWN_CONTRACT_VERSIONS,
+  SyncContractError,
+  acceptTenants,
+  createD1Inbox,
+  createProcessor,
+  createSnapshotClient,
+  handleIngestRequest,
+  parseEnvelope,
+  parseSubject,
+  signWebhook,
+  verifyWebhook
+};
+//# sourceMappingURL=sync.js.map