@selfxyz/enterprise-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor: Social Connect Labs, Inc.
+
+Licensed Work: The code in this folder and all folders nested within it, including all files and components unless explicitly stated otherwise.
+
+Additional Use Grant: Any use for development, testing, and deployment on networks approved by Social Connect Labs, Inc., including internal business operations and academic research.
+
+Change Date: 2029-06-11
+
+Change License: Apache License, Version 2.0
+
+================================================================
+
+Business Source License 1.1
+
+Copyright (C) 2025 Social Connect Labs, Inc.
+
+The contents of this repository are licensed under the Business Source License 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:
+
+https://spdx.org/licenses/BUSL-1.1.html
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+Change Date
+
+The Change Date is the later of four years from the date this repository was published or 2029-06-11.
+
+Change License
+
+On the Change Date, the contents of this repository will be made available under the terms of the Apache License, Version 2.0, as published by the Apache Software Foundation.
+
+See the License for the specific language governing permissions and limitations under the Business Source License.

package/README.md

@@ -0,0 +1,98 @@
+# @selfxyz/enterprise-sdk
+
+Official Node/TypeScript SDK for the [Self.xyz](https://self.xyz) Enterprise API — create verification sessions and verify webhooks with typed payloads.
+
+> **Pre-1.0 stability**: this SDK is under active development. Minor versions may include breaking changes until `1.0.0`. Pin to an exact version in production.
+
+## Requirements
+
+- Node.js **≥ 20**
+- ESM-only (the package is `"type": "module"`; use it from ESM consumers, or via dynamic `import()` from CommonJS)
+
+## Install
+
+```bash
+pnpm add @selfxyz/enterprise-sdk
+# or
+npm install @selfxyz/enterprise-sdk
+# or
+yarn add @selfxyz/enterprise-sdk
+```
+
+## Quickstart
+
+Create a verification session and hand the returned URL to your end user:
+
+```ts
+import { SelfClient } from '@selfxyz/enterprise-sdk';
+
+const self = new SelfClient({ apiKey: process.env.SELF_API_KEY! });
+
+const session = await self.sessions.create({
+  flowId: '<your-flow-uuid>',
+  externalUuid: 'user-123',
+});
+
+// Redirect the end user here:
+console.log(session.verificationUrl);
+```
+
+To look up a session later:
+
+```ts
+const detail = await self.sessions.get(session.id);
+console.log(detail.status); // 'pending' | 'valid' | 'invalid' | 'error' | 'expired'
+```
+
+## Webhook verification
+
+Use `SelfWebhooks.verify` to validate an inbound webhook signature and return a typed event:
+
+```ts
+import { SelfWebhooks } from '@selfxyz/enterprise-sdk';
+
+app.post('/webhooks/self', (req, res) => {
+  try {
+    const event = SelfWebhooks.verify(
+      req.body, // raw string or Buffer — do NOT pre-parse
+      req.headers, // must include the signature headers as received
+      process.env.SELF_WEBHOOK_SECRET!, // whsec_... from the Self dashboard
+    );
+
+    console.log(event.type, event.verification_id);
+    res.status(200).end();
+  } catch (err) {
+    res.status(400).end();
+  }
+});
+```
+
+The raw request body must be passed exactly as received — middleware that JSON-parses the body before signature verification will cause it to fail.
+
+## Error handling
+
+The SDK throws two distinct error types:
+
+```ts
+import { SelfApiError, WebhookVerificationError } from '@selfxyz/enterprise-sdk';
+
+try {
+  await self.sessions.create({ flowId, externalUuid });
+} catch (err) {
+  if (err instanceof SelfApiError) {
+    err.statusCode; // number — HTTP status
+    err.code; // string — machine-readable error code
+    err.message; // string — human-readable
+    err.details; // Record<string, unknown> | undefined
+  }
+  throw err;
+}
+```
+
+`WebhookVerificationError` is thrown by `SelfWebhooks.verify` when a signature is invalid or missing.
+
+## License
+
+Licensed under the [Business Source License 1.1](./LICENSE). © 2025 Socialconnect Labs, Inc.
+
+On **2029-06-11** the license converts automatically to the **Apache License, Version 2.0**.

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+import { z } from 'zod';
+export { WebhookVerificationError } from 'svix';
+
+declare const verificationCompleted: z.ZodObject<{
+    type: z.ZodLiteral<"verification.completed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    flow_id: z.ZodString;
+    flow_version_id: z.ZodString;
+    environment: z.ZodEnum<["test", "live"]>;
+    status: z.ZodEnum<["valid", "invalid", "error", "expired"]>;
+    proof_attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /** Raw ZK proof JSON. Present when status is 'valid'; null otherwise. */
+    proof: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    verified_at: z.ZodString;
+    storage_state: z.ZodEnum<["pending", "committed", "failed"]>;
+    storage_uri: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.completed";
+    status: "valid" | "invalid" | "error" | "expired";
+    verification_id: string;
+    external_uuid: string;
+    flow_id: string;
+    flow_version_id: string;
+    environment: "test" | "live";
+    proof_attributes: Record<string, unknown>;
+    proof: Record<string, unknown> | null;
+    verified_at: string;
+    storage_state: "pending" | "committed" | "failed";
+    storage_uri: string | null;
+}, {
+    type: "verification.completed";
+    status: "valid" | "invalid" | "error" | "expired";
+    verification_id: string;
+    external_uuid: string;
+    flow_id: string;
+    flow_version_id: string;
+    environment: "test" | "live";
+    proof_attributes: Record<string, unknown>;
+    proof: Record<string, unknown> | null;
+    verified_at: string;
+    storage_state: "pending" | "committed" | "failed";
+    storage_uri: string | null;
+}>;
+declare const verificationStorageCommitted: z.ZodObject<{
+    type: z.ZodLiteral<"verification.storage_committed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    storage_uri: z.ZodString;
+    credential_id: z.ZodString;
+    committed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.storage_committed";
+    verification_id: string;
+    external_uuid: string;
+    storage_uri: string;
+    credential_id: string;
+    committed_at: string;
+}, {
+    type: "verification.storage_committed";
+    verification_id: string;
+    external_uuid: string;
+    storage_uri: string;
+    credential_id: string;
+    committed_at: string;
+}>;
+declare const verificationStorageFailed: z.ZodObject<{
+    type: z.ZodLiteral<"verification.storage_failed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    error: z.ZodString;
+    failed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.storage_failed";
+    error: string;
+    verification_id: string;
+    external_uuid: string;
+    failed_at: string;
+}, {
+    type: "verification.storage_failed";
+    error: string;
+    verification_id: string;
+    external_uuid: string;
+    failed_at: string;
+}>;
+declare const webhookEvent: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"verification.completed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    flow_id: z.ZodString;
+    flow_version_id: z.ZodString;
+    environment: z.ZodEnum<["test", "live"]>;
+    status: z.ZodEnum<["valid", "invalid", "error", "expired"]>;
+    proof_attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /** Raw ZK proof JSON. Present when status is 'valid'; null otherwise. */
+    proof: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    verified_at: z.ZodString;
+    storage_state: z.ZodEnum<["pending", "committed", "failed"]>;
+    storage_uri: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.completed";
+    status: "valid" | "invalid" | "error" | "expired";
+    verification_id: string;
+    external_uuid: string;
+    flow_id: string;
+    flow_version_id: string;
+    environment: "test" | "live";
+    proof_attributes: Record<string, unknown>;
+    proof: Record<string, unknown> | null;
+    verified_at: string;
+    storage_state: "pending" | "committed" | "failed";
+    storage_uri: string | null;
+}, {
+    type: "verification.completed";
+    status: "valid" | "invalid" | "error" | "expired";
+    verification_id: string;
+    external_uuid: string;
+    flow_id: string;
+    flow_version_id: string;
+    environment: "test" | "live";
+    proof_attributes: Record<string, unknown>;
+    proof: Record<string, unknown> | null;
+    verified_at: string;
+    storage_state: "pending" | "committed" | "failed";
+    storage_uri: string | null;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"verification.storage_committed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    storage_uri: z.ZodString;
+    credential_id: z.ZodString;
+    committed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.storage_committed";
+    verification_id: string;
+    external_uuid: string;
+    storage_uri: string;
+    credential_id: string;
+    committed_at: string;
+}, {
+    type: "verification.storage_committed";
+    verification_id: string;
+    external_uuid: string;
+    storage_uri: string;
+    credential_id: string;
+    committed_at: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"verification.storage_failed">;
+    verification_id: z.ZodString;
+    external_uuid: z.ZodString;
+    error: z.ZodString;
+    failed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "verification.storage_failed";
+    error: string;
+    verification_id: string;
+    external_uuid: string;
+    failed_at: string;
+}, {
+    type: "verification.storage_failed";
+    error: string;
+    verification_id: string;
+    external_uuid: string;
+    failed_at: string;
+}>]>;
+type VerificationCompletedPayload = z.infer<typeof verificationCompleted>;
+type VerificationStorageCommittedPayload = z.infer<typeof verificationStorageCommitted>;
+type VerificationStorageFailedPayload = z.infer<typeof verificationStorageFailed>;
+type WebhookEvent = z.infer<typeof webhookEvent>;
+
+declare const createSessionBody: z.ZodObject<{
+    flowId: z.ZodString;
+    externalUuid: z.ZodString;
+    expiresInSeconds: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>, Record<string, unknown> | undefined, Record<string, unknown> | undefined>;
+    successUrl: z.ZodOptional<z.ZodString>;
+    failureUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    flowId: string;
+    externalUuid: string;
+    expiresInSeconds: number;
+    metadata?: Record<string, unknown> | undefined;
+    successUrl?: string | undefined;
+    failureUrl?: string | undefined;
+}, {
+    flowId: string;
+    externalUuid: string;
+    expiresInSeconds?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    successUrl?: string | undefined;
+    failureUrl?: string | undefined;
+}>;
+/** Output type (after Zod defaults are applied — expiresInSeconds is required). */
+type CreateSessionBody = z.infer<typeof createSessionBody>;
+/** Input type (what the SDK consumer passes — expiresInSeconds is optional). */
+type CreateSessionInput = z.input<typeof createSessionBody>;
+
+declare const createSessionResponse: z.ZodObject<{
+    id: z.ZodString;
+    externalUuid: z.ZodString;
+    status: z.ZodLiteral<"pending">;
+    flowVersionId: z.ZodString;
+    /** Single-use token (e.g. `verify_live_<random>`). */
+    verificationToken: z.ZodString;
+    /** Full URL to redirect the end-user to (e.g. `https://verify.self.xyz/s/<token>`). */
+    verificationUrl: z.ZodString;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    completedAt: z.ZodNull;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "pending";
+    externalUuid: string;
+    flowVersionId: string;
+    verificationToken: string;
+    verificationUrl: string;
+    createdAt: string;
+    expiresAt: string;
+    completedAt: null;
+}, {
+    id: string;
+    status: "pending";
+    externalUuid: string;
+    flowVersionId: string;
+    verificationToken: string;
+    verificationUrl: string;
+    createdAt: string;
+    expiresAt: string;
+    completedAt: null;
+}>;
+declare const sessionDetailResponse: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<["pending", "valid", "invalid", "error", "expired"]>;
+    createdAt: z.ZodString;
+    completedAt: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodString;
+    flowVersionId: z.ZodString;
+    externalUuid: z.ZodString;
+    metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    predicatesConfig: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    proofAttributes: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    storage: z.ZodObject<{
+        state: z.ZodEnum<["pending", "committed", "failed"]>;
+        uri: z.ZodNullable<z.ZodString>;
+        credentialId: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        state: "pending" | "committed" | "failed";
+        uri: string | null;
+        credentialId: string | null;
+    }, {
+        state: "pending" | "committed" | "failed";
+        uri: string | null;
+        credentialId: string | null;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "valid" | "pending" | "invalid" | "error" | "expired";
+    externalUuid: string;
+    metadata: Record<string, unknown> | null;
+    flowVersionId: string;
+    createdAt: string;
+    expiresAt: string;
+    completedAt: string | null;
+    predicatesConfig: Record<string, unknown> | null;
+    proofAttributes: Record<string, unknown> | null;
+    storage: {
+        state: "pending" | "committed" | "failed";
+        uri: string | null;
+        credentialId: string | null;
+    };
+}, {
+    id: string;
+    status: "valid" | "pending" | "invalid" | "error" | "expired";
+    externalUuid: string;
+    metadata: Record<string, unknown> | null;
+    flowVersionId: string;
+    createdAt: string;
+    expiresAt: string;
+    completedAt: string | null;
+    predicatesConfig: Record<string, unknown> | null;
+    proofAttributes: Record<string, unknown> | null;
+    storage: {
+        state: "pending" | "committed" | "failed";
+        uri: string | null;
+        credentialId: string | null;
+    };
+}>;
+type CreateSessionResponse = z.infer<typeof createSessionResponse>;
+type SessionDetailResponse = z.infer<typeof sessionDetailResponse>;
+
+interface SelfClientOptions {
+    /** Bearer API key (e.g. `sk_live_...`). */
+    apiKey: string;
+    /** Environment hint. The actual environment is embedded in the API key via Unkey. */
+    environment?: 'test' | 'live';
+    /** Override the base URL (default: `https://api.self.xyz`). */
+    baseUrl?: string;
+}
+/**
+ * Node/TS client for the Self.xyz Edge API.
+ *
+ * ```ts
+ * const self = new SelfClient({ apiKey: 'sk_live_...' });
+ * const session = await self.sessions.create({
+ *   flowId: '<uuid>',
+ *   externalUuid: 'user-123',
+ * });
+ * console.log(session.verificationUrl);
+ * ```
+ */
+declare class SelfClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    readonly sessions: {
+        create: (params: CreateSessionInput) => Promise<CreateSessionResponse>;
+        get: (id: string) => Promise<SessionDetailResponse>;
+    };
+    constructor(options: SelfClientOptions);
+    private request;
+    private createSession;
+    private getSession;
+}
+
+interface WebhookHeaders {
+    'svix-id': string;
+    'svix-timestamp': string;
+    'svix-signature': string;
+}
+/**
+ * Verify and parse inbound Self webhook payloads signed by Svix.
+ *
+ * ```ts
+ * app.post('/webhooks/self', (req, res) => {
+ *   const event = SelfWebhooks.verify(
+ *     req.body,            // raw string body
+ *     req.headers,         // must include svix-id, svix-timestamp, svix-signature
+ *     process.env.SELF_WEBHOOK_SECRET!, // whsec_... from dashboard
+ *   );
+ *   console.log(event.type, event.verification_id);
+ * });
+ * ```
+ */
+declare class SelfWebhooks {
+    /**
+     * Verify a webhook signature and return the typed event payload.
+     *
+     * @param payload  Raw request body (string or Buffer).
+     * @param headers  Object containing `svix-id`, `svix-timestamp`, `svix-signature`.
+     * @param secret   Webhook signing secret (`whsec_...` from the Self dashboard).
+     * @returns        Parsed and verified {@link WebhookEvent}.
+     * @throws         `WebhookVerificationError` if the signature is invalid.
+     * @throws         `ZodError` if the payload shape doesn't match any known event type.
+     */
+    static verify(payload: string | Buffer, headers: WebhookHeaders | Record<string, string>, secret: string): WebhookEvent;
+}
+
+interface ApiErrorBody {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Thrown when the Self API returns a non-2xx response.
+ * Wraps the standard `{ error: { code, message, details? } }` envelope.
+ */
+declare class SelfApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(statusCode: number, body: ApiErrorBody);
+}
+
+export { type ApiErrorBody, type CreateSessionBody, type CreateSessionInput, SelfApiError, SelfClient, type SelfClientOptions, SelfWebhooks, type CreateSessionResponse as Session, type SessionDetailResponse as SessionDetail, type VerificationCompletedPayload, type VerificationStorageCommittedPayload, type VerificationStorageFailedPayload, type WebhookEvent, type WebhookHeaders, createSessionBody, createSessionResponse, sessionDetailResponse, verificationCompleted, verificationStorageCommitted, verificationStorageFailed, webhookEvent };

package/dist/index.js

@@ -0,0 +1,341 @@
+// src/errors.ts
+import { WebhookVerificationError } from "svix";
+var SelfApiError = class extends Error {
+  statusCode;
+  code;
+  details;
+  constructor(statusCode, body) {
+    super(body.message);
+    this.name = "SelfApiError";
+    this.statusCode = statusCode;
+    this.code = body.code;
+    this.details = body.details;
+  }
+};
+
+// src/client.ts
+var SelfClient = class {
+  apiKey;
+  baseUrl;
+  sessions;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("apiKey is required");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://api.self.xyz").replace(/\/+$/, "");
+    this.sessions = {
+      create: (params) => this.createSession(params),
+      get: (id) => this.getSession(id)
+    };
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await res.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = void 0;
+    }
+    if (!res.ok) {
+      const envelope = json;
+      throw new SelfApiError(res.status, {
+        code: envelope?.error?.code ?? "unknown_error",
+        message: envelope?.error?.message ?? (text || res.statusText),
+        ...envelope?.error?.details ? { details: envelope.error.details } : {}
+      });
+    }
+    return json;
+  }
+  createSession(params) {
+    return this.request("POST", "/v1/sessions", params);
+  }
+  getSession(id) {
+    return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/webhooks.ts
+import { z as z6 } from "zod";
+import { Webhook } from "svix";
+
+// ../schemas/dist/stripe-events.js
+import { z } from "zod";
+var stripeEventBase = z.object({
+  id: z.string().startsWith("evt_"),
+  type: z.string(),
+  created: z.number(),
+  data: z.object({ object: z.unknown() })
+});
+var chargeRefunded = stripeEventBase.extend({
+  type: z.literal("charge.refunded"),
+  data: z.object({
+    object: z.object({
+      id: z.string().startsWith("ch_"),
+      customer: z.string().startsWith("cus_").nullable(),
+      amount_refunded: z.number()
+    })
+  })
+});
+var invoicePaid = stripeEventBase.extend({
+  type: z.literal("invoice.paid"),
+  data: z.object({
+    object: z.object({
+      id: z.string().startsWith("in_"),
+      customer: z.string().startsWith("cus_"),
+      // API version 2026-04-22.dahlia moved the subscription id from the
+      // top-level `subscription` field to `parent.subscription_details.subscription`.
+      // We accept BOTH: routes will prefer the new location and fall back
+      // to the legacy field, so a downgrade to an older API version stays
+      // safe.
+      subscription: z.string().startsWith("sub_").nullable().optional(),
+      parent: z.object({
+        subscription_details: z.object({
+          subscription: z.string().startsWith("sub_").nullable().optional()
+        }).nullable().optional()
+      }).nullable().optional(),
+      period_end: z.number().int(),
+      billing_reason: z.string().optional(),
+      lines: z.object({
+        data: z.array(z.object({
+          // Each line item also has its own subscription details + price
+          // in the new API. The route reads price metadata from here.
+          price: z.object({
+            id: z.string(),
+            metadata: z.record(z.string(), z.string()).optional()
+          }).nullable().optional(),
+          pricing: z.object({
+            price_details: z.object({
+              price: z.string()
+            }).nullable().optional()
+          }).nullable().optional(),
+          // API version 2026-04-22.dahlia: the invoice's top-level
+          // `period_start`/`period_end` collapsed to invoice-creation
+          // time on single-line subscription invoices; the real billing
+          // cycle lives ONLY here on the line item. Route reads
+          // `period.end` for the credit-grant `expires_at`.
+          period: z.object({
+            start: z.number().int(),
+            end: z.number().int()
+          }).optional()
+        })).min(1)
+      })
+    })
+  })
+});
+var subscriptionData = z.object({
+  id: z.string().startsWith("sub_"),
+  customer: z.string().startsWith("cus_"),
+  status: z.string(),
+  // API version 2026-04-22.dahlia moved `current_period_end` from the
+  // subscription top level onto each subscription item (items.data[].current_period_end).
+  // Accept both — route handler prefers the new per-item location and
+  // falls back to the legacy field.
+  current_period_end: z.number().int().optional(),
+  cancel_at_period_end: z.boolean().optional(),
+  items: z.object({
+    data: z.array(z.object({
+      current_period_end: z.number().int().optional(),
+      current_period_start: z.number().int().optional(),
+      price: z.object({
+        id: z.string(),
+        recurring: z.object({ interval: z.enum(["month", "year"]) }).nullable().optional()
+      })
+    })).min(1)
+  })
+});
+var customerSubscriptionCreated = stripeEventBase.extend({
+  type: z.literal("customer.subscription.created"),
+  data: z.object({ object: subscriptionData })
+});
+var customerSubscriptionUpdated = stripeEventBase.extend({
+  type: z.literal("customer.subscription.updated"),
+  data: z.object({ object: subscriptionData })
+});
+var customerSubscriptionDeleted = stripeEventBase.extend({
+  type: z.literal("customer.subscription.deleted"),
+  data: z.object({ object: subscriptionData })
+});
+var handledStripeEvent = z.discriminatedUnion("type", [
+  chargeRefunded,
+  invoicePaid,
+  customerSubscriptionCreated,
+  customerSubscriptionUpdated,
+  customerSubscriptionDeleted
+]);
+
+// ../schemas/dist/metronome-events.js
+import { z as z2 } from "zod";
+var creditCreate = z2.object({
+  id: z2.string(),
+  type: z2.literal("credit.create"),
+  timestamp: z2.string().datetime(),
+  environment_type: z2.string().optional(),
+  credit_id: z2.string(),
+  customer_id: z2.string(),
+  // Populated for contract-scoped credits; absent/null for standalone
+  // CreditGrants (the path Self currently uses).
+  contract_id: z2.string().nullable().optional(),
+  parent_recurring_credit_id: z2.string().nullable().optional(),
+  // Custom-field buckets are scattered by entity type. The `source` tag
+  // we set on grant creation lands under `credit_custom_fields`. Used to
+  // distinguish lifetime grants (Free signup, Enterprise admin) from
+  // periodic grants (Stripe invoice.paid). Periodic grants are applied
+  // to Firestore inline by the invoice.paid handler; the credit-create
+  // handler skips them so the same balance change isn't double-applied.
+  // Absence of the tag defaults to lifetime (the safe-direction fallback).
+  credit_custom_fields: z2.object({
+    source: z2.enum(["lifetime", "periodic"]).optional()
+  }).passthrough().optional(),
+  contract_custom_fields: z2.record(z2.string(), z2.string()).optional(),
+  customer_custom_fields: z2.record(z2.string(), z2.string()).optional()
+});
+var commitCreate = z2.object({
+  id: z2.string(),
+  type: z2.literal("commit.create"),
+  timestamp: z2.string().datetime(),
+  environment_type: z2.string().optional(),
+  commit_id: z2.string(),
+  customer_id: z2.string(),
+  contract_id: z2.string().nullable().optional(),
+  commit_custom_fields: z2.object({
+    source: z2.enum(["lifetime", "periodic"]).optional()
+  }).passthrough().optional(),
+  contract_custom_fields: z2.record(z2.string(), z2.string()).optional(),
+  customer_custom_fields: z2.record(z2.string(), z2.string()).optional()
+});
+var handledMetronomeEvent = z2.discriminatedUnion("type", [creditCreate, commitCreate]);
+
+// ../schemas/dist/webhook-events.js
+import { z as z3 } from "zod";
+var verificationCompleted = z3.object({
+  type: z3.literal("verification.completed"),
+  verification_id: z3.string(),
+  external_uuid: z3.string(),
+  flow_id: z3.string(),
+  flow_version_id: z3.string(),
+  environment: z3.enum(["test", "live"]),
+  status: z3.enum(["valid", "invalid", "error", "expired"]),
+  proof_attributes: z3.record(z3.string(), z3.unknown()),
+  /** Raw ZK proof JSON. Present when status is 'valid'; null otherwise. */
+  proof: z3.record(z3.string(), z3.unknown()).nullable(),
+  verified_at: z3.string().datetime(),
+  storage_state: z3.enum(["pending", "committed", "failed"]),
+  storage_uri: z3.string().nullable()
+});
+var verificationStorageCommitted = z3.object({
+  type: z3.literal("verification.storage_committed"),
+  verification_id: z3.string(),
+  external_uuid: z3.string(),
+  storage_uri: z3.string(),
+  credential_id: z3.string(),
+  committed_at: z3.string().datetime()
+});
+var verificationStorageFailed = z3.object({
+  type: z3.literal("verification.storage_failed"),
+  verification_id: z3.string(),
+  external_uuid: z3.string(),
+  error: z3.string(),
+  failed_at: z3.string().datetime()
+});
+var webhookEvent = z3.discriminatedUnion("type", [
+  verificationCompleted,
+  verificationStorageCommitted,
+  verificationStorageFailed
+]);
+
+// ../schemas/dist/session-requests.js
+import { z as z4 } from "zod";
+var createSessionBody = z4.object({
+  flowId: z4.string().uuid(),
+  externalUuid: z4.string().min(1).max(128),
+  expiresInSeconds: z4.number().int().min(60).max(86400).default(3600),
+  metadata: z4.record(z4.unknown()).optional().refine((val) => !val || JSON.stringify(val).length <= 4096, {
+    message: "metadata must be 4KB or less when serialized"
+  }),
+  successUrl: z4.string().url().optional(),
+  failureUrl: z4.string().url().optional()
+});
+
+// ../schemas/dist/session-responses.js
+import { z as z5 } from "zod";
+var createSessionResponse = z5.object({
+  id: z5.string(),
+  externalUuid: z5.string(),
+  status: z5.literal("pending"),
+  flowVersionId: z5.string(),
+  /** Single-use token (e.g. `verify_live_<random>`). */
+  verificationToken: z5.string(),
+  /** Full URL to redirect the end-user to (e.g. `https://verify.self.xyz/s/<token>`). */
+  verificationUrl: z5.string(),
+  createdAt: z5.string().datetime(),
+  expiresAt: z5.string().datetime(),
+  completedAt: z5.null()
+});
+var sessionDetailResponse = z5.object({
+  id: z5.string(),
+  status: z5.enum(["pending", "valid", "invalid", "error", "expired"]),
+  createdAt: z5.string().datetime(),
+  completedAt: z5.string().datetime().nullable(),
+  expiresAt: z5.string().datetime(),
+  flowVersionId: z5.string(),
+  externalUuid: z5.string(),
+  metadata: z5.record(z5.string(), z5.unknown()).nullable(),
+  predicatesConfig: z5.record(z5.string(), z5.unknown()).nullable(),
+  proofAttributes: z5.record(z5.string(), z5.unknown()).nullable(),
+  storage: z5.object({
+    state: z5.enum(["pending", "committed", "failed"]),
+    uri: z5.string().nullable(),
+    credentialId: z5.string().nullable()
+  })
+});
+
+// src/webhooks.ts
+var forwardCompatibleEvent = z6.discriminatedUnion("type", [
+  verificationCompleted.passthrough(),
+  verificationStorageCommitted.passthrough(),
+  verificationStorageFailed.passthrough()
+]);
+var SelfWebhooks = class {
+  /**
+   * Verify a webhook signature and return the typed event payload.
+   *
+   * @param payload  Raw request body (string or Buffer).
+   * @param headers  Object containing `svix-id`, `svix-timestamp`, `svix-signature`.
+   * @param secret   Webhook signing secret (`whsec_...` from the Self dashboard).
+   * @returns        Parsed and verified {@link WebhookEvent}.
+   * @throws         `WebhookVerificationError` if the signature is invalid.
+   * @throws         `ZodError` if the payload shape doesn't match any known event type.
+   */
+  static verify(payload, headers, secret) {
+    const wh = new Webhook(secret);
+    const verified = wh.verify(
+      typeof payload === "string" ? payload : payload.toString("utf-8"),
+      headers
+    );
+    return forwardCompatibleEvent.parse(verified);
+  }
+};
+export {
+  SelfApiError,
+  SelfClient,
+  SelfWebhooks,
+  WebhookVerificationError,
+  createSessionBody,
+  createSessionResponse,
+  sessionDetailResponse,
+  verificationCompleted,
+  verificationStorageCommitted,
+  verificationStorageFailed,
+  webhookEvent
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@selfxyz/enterprise-sdk",
+  "version": "0.1.0",
+  "description": "Node/TS SDK for Self.xyz enterprise verification — session creation, webhook signature verification, typed payloads.",
+  "license": "BUSL-1.1",
+  "homepage": "https://self.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selfxyz/self-dashboard.git",
+    "directory": "packages/self-enterprise-sdk"
+  },
+  "keywords": [
+    "self",
+    "selfxyz",
+    "identity",
+    "verification",
+    "zk",
+    "passport",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "name": "@selfxyz/enterprise-sdk",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,yaml,yml}\" --ignore-path ../../.prettierignore",
+    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,yaml,yml}\" --ignore-path ../../.prettierignore",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "svix": "^1.92.2",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@self/schemas": "workspace:*",
+    "@types/node": "^22.10.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}