@base44-preview/platform 0.1.0-pr.316.56344d6 → 0.1.0-pr.319.1e807d1

package/README.md

@@ -10,9 +10,9 @@ shared socket. It is independent of the app SDK (`@base44/sdk`).
 The workspace must have white-label sockets enabled; this SDK does not open sessions.
 
 ```ts
-import { Base44PlatformClient } from "@base44/platform";
+import { createBase44PlatformClient } from "@base44/platform";
 
-const client = new Base44PlatformClient({
+const client = createBase44PlatformClient({
   serverUrl: "https://base44.app",
   async getSessionToken() {
     const response = await fetch("/api/builder-socket-session", { method: "POST" });
@@ -34,6 +34,60 @@ subscription.unsubscribe();
 builder.close();
 ```
 
+## Receiving webhooks (server)
+
+`@base44/platform/server` verifies Base44 outbound webhooks and answers the endpoint
+activation challenge. It uses WebCrypto only (Node 20+, Deno, Bun, Workers, edge runtimes) and
+makes no network calls: pass your workspace's public keys (`whpk_…`) explicitly.
+
+The simplest route is `createHandler`. It reads the raw body, verifies it, answers the
+activation challenge and picks the status code: 400 for a delivery that fails verification,
+500 when your keys are misconfigured or a callback throws (Base44 retries), 204 otherwise,
+including for event types you have no handler for.
+
+```ts
+import { createBase44PlatformServer } from "@base44/platform/server";
+
+const platform = createBase44PlatformServer({
+  serverUrl: "https://base44.app",
+  apiKey: process.env.BASE44_API_KEY!,
+  webhooks: { publicKeys: process.env.BASE44_WEBHOOK_PUBLIC_KEYS },
+});
+
+export const POST = platform.webhooks.createHandler({
+  on: {
+    "app.deleted.v1": async event => forget(event.data.app_id), // event is narrowed per type
+  },
+  onEvent: event => log(event.type),      // every event, before its handler
+  onSuccess: event => {},                 // return a Response to replace the 204
+  onError: (error, event) => report(error), // return a Response to replace the 400/500
+});
+```
+
+For full control, verify and dispatch yourself:
+
+```ts
+export async function POST(request: Request) {
+  const rawBody = await request.text(); // exactly as received
+  let event;
+  try {
+    event = await platform.webhooks.verifyEvent(rawBody, request.headers);
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
+    throw error; // missing/malformed keys: a 500, so Base44 retries
+  }
+  switch (event.type) {
+    case "webhook.test.v1": return Response.json({ challenge: event.data.challenge }); // activates the endpoint
+    case "app.deleted.v1": await forget(event.data.app_id); break;
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+Delivery is at least once with no ordering guarantee: deduplicate on `event.id`, and answer
+2xx to event types you do not handle. Event types are generated from the schemas published at
+`https://base44.com/webhooks/schemas`; run `npm run generate:webhooks` to refresh them.
+
 ## Sessions
 
 `/api/builder-socket-session` is your backend's route, not an SDK endpoint. It opens a
@@ -55,7 +109,7 @@ older one, which stops with `session_replaced`. Open one session per page.
 
 ## Lifecycle
 
-`new Base44PlatformClient({ serverUrl, getSessionToken })` creates a lightweight module
+`createBase44PlatformClient({ serverUrl, getSessionToken })` returns a lightweight module
 container: no Socket.IO instance, timers, token request or network activity. Its
 `builder` module follows the server SDK's module-factory pattern.
 

package/dist/client/client.d.ts

@@ -1,9 +1,3 @@
-import type { PlatformClientOptions } from "./client.types.js";
-import type { BuilderModule } from "./modules/builder.types.js";
-/** Browser platform client. Construction creates no sockets, timers or network requests. */
-export declare class Base44PlatformClient {
-    /** Lazy builder subscriptions with independent session lifecycles. */
-    readonly builder: BuilderModule;
-    /** Configure shared service/auth settings; each module initializes its own resources. */
-    constructor(options: PlatformClientOptions);
-}
+import type { Base44PlatformClient, PlatformClientOptions } from "./client.types.js";
+/** Create a browser platform client. Creates no sockets, timers or network requests; each module initializes its own resources. */
+export declare function createBase44PlatformClient(options: PlatformClientOptions): Base44PlatformClient;

package/dist/client/client.js

@@ -1,9 +1,8 @@
 import { normalizeServerUrl } from "../shared/server-url.js";
 import { createBuilder } from "./modules/builder.js";
-/** Browser platform client. Construction creates no sockets, timers or network requests. */
-export class Base44PlatformClient {
-    /** Configure shared service/auth settings; each module initializes its own resources. */
-    constructor(options) {
-        this.builder = Object.freeze(createBuilder({ ...options, serverUrl: normalizeServerUrl(options.serverUrl) }));
-    }
+/** Create a browser platform client. Creates no sockets, timers or network requests; each module initializes its own resources. */
+export function createBase44PlatformClient(options) {
+    return Object.freeze({
+        builder: Object.freeze(createBuilder({ ...options, serverUrl: normalizeServerUrl(options.serverUrl) })),
+    });
 }

package/dist/client/client.types.d.ts

@@ -1,3 +1,4 @@
+import type { BuilderModule } from "./modules/builder.types.js";
 /** Shared configuration for browser platform modules. Never supply an API key. */
 export interface PlatformClientOptions {
     /** Origin of the platform service, e.g. https://base44.app. No path/query/credentials. */
@@ -10,3 +11,8 @@ export interface PlatformClientOptions {
      */
     getSessionToken: () => string | Promise<string>;
 }
+/** Browser platform client, returned by `createBase44PlatformClient`. */
+export interface Base44PlatformClient {
+    /** Lazy builder subscriptions with independent session lifecycles. */
+    readonly builder: BuilderModule;
+}

package/dist/client/index.d.ts

@@ -1,7 +1,7 @@
 /** Browser platform modules, separate from the runtime and server SDKs. */
-export { Base44PlatformClient } from "./client.js";
+export { createBase44PlatformClient } from "./client.js";
 export { PlatformSocketError } from "./errors.js";
 export type { PlatformSocketErrorCode } from "./errors.types.js";
-export type { PlatformClientOptions } from "./client.types.js";
+export type { Base44PlatformClient, PlatformClientOptions } from "./client.types.js";
 export type { BuilderModule, BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./modules/builder.types.js";
 export type { AppStatus, AppStatusChanged, BranchScoped, ChatMessage, ImageResolved, MessageParams, MessageRemoved, MessageUpdated, PlatformEvent, PlatformEventMap, PreviewNavigationRequested, QueueItem, QueueUpdated, Snapshot, SnapshotQueue, TaskProgressed, ToolArguments, ToolCall, ToolDisplay, ToolEntityMutationArguments, ToolGuardApproval, ToolMediaArguments, ToolMediaResult, ToolPackageArguments, ToolPackageOperation, ToolPlanArguments, ToolPlanUpdate, ToolPrdArguments, ToolQuestion, ToolQuestionAnswer, ToolQuestionArguments, ToolQuestionInput, ToolQuestionOption, ToolSecretArguments, ToolSecretField, } from "./modules/builder.events.types.js";

package/dist/client/index.js

@@ -1,3 +1,3 @@
 /** Browser platform modules, separate from the runtime and server SDKs. */
-export { Base44PlatformClient } from "./client.js";
+export { createBase44PlatformClient } from "./client.js";
 export { PlatformSocketError } from "./errors.js";

package/dist/server/errors.d.ts

@@ -0,0 +1,15 @@
+import type { WebhookConfigurationErrorCode, WebhookVerificationErrorCode } from "./errors.types.js";
+/** A webhook delivery that cannot be trusted. The message never includes the body or signature. */
+export declare class WebhookVerificationError extends Error {
+    /** Stable machine-readable reason. */
+    readonly code: WebhookVerificationErrorCode;
+    /** Create an error carrying only the reason. */
+    constructor(code: WebhookVerificationErrorCode);
+}
+/** Webhook public keys are missing or malformed, so no delivery can be verified. */
+export declare class WebhookConfigurationError extends Error {
+    /** Stable machine-readable reason. */
+    readonly code: WebhookConfigurationErrorCode;
+    /** Create an error describing the misconfiguration. */
+    constructor(code: WebhookConfigurationErrorCode, detail: string);
+}

package/dist/server/errors.js

@@ -0,0 +1,18 @@
+/** A webhook delivery that cannot be trusted. The message never includes the body or signature. */
+export class WebhookVerificationError extends Error {
+    /** Create an error carrying only the reason. */
+    constructor(code) {
+        super(`Webhook verification failed: ${code}`);
+        this.name = "WebhookVerificationError";
+        this.code = code;
+    }
+}
+/** Webhook public keys are missing or malformed, so no delivery can be verified. */
+export class WebhookConfigurationError extends Error {
+    /** Create an error describing the misconfiguration. */
+    constructor(code, detail) {
+        super(`Webhook configuration: ${detail}`);
+        this.name = "WebhookConfigurationError";
+        this.code = code;
+    }
+}

package/dist/server/errors.types.d.ts

@@ -0,0 +1,4 @@
+/** Why a delivery was refused. Respond 400: the request is not a genuine, current Base44 event. */
+export type WebhookVerificationErrorCode = "missing_headers" | "timestamp_outside_tolerance" | "no_signature_entries" | "signature_mismatch" | "invalid_payload";
+/** Why verification could not run at all. This is your deployment, not the request: let it surface as a 500 so Base44 retries. */
+export type WebhookConfigurationErrorCode = "missing_public_keys" | "invalid_public_key";

package/dist/server/errors.types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/index.d.ts

@@ -1,3 +1,6 @@
 /** Server platform modules, authenticated with a workspace API key. */
-export { Base44PlatformServer } from "./server.js";
-export type { PlatformServerOptions } from "./server.types.js";
+export { createBase44PlatformServer } from "./server.js";
+export { WebhookConfigurationError, WebhookVerificationError } from "./errors.js";
+export type { WebhookConfigurationErrorCode, WebhookVerificationErrorCode } from "./errors.types.js";
+export type { Base44PlatformServer, PlatformServerOptions } from "./server.types.js";
+export type { AppCreatedV1Data, AppDeletedV1Data, AppPublishedV1Data, AppRestoredV1Data, AppUnpublishedV1Data, CloudEvent, CreateHandlerOptions, DeliveredWebhookEvent, VerifyEventOptions, WebhookEventHandlers, WebhookEvent, WebhookEventMap, WebhookEventType, WebhookHeaders, WebhookPublicKeys, WebhooksModule, WebhooksOptions, WebhookTestV1Data, } from "./modules/webhooks.types.js";

package/dist/server/index.js

@@ -1,2 +1,3 @@
 /** Server platform modules, authenticated with a workspace API key. */
-export { Base44PlatformServer } from "./server.js";
+export { createBase44PlatformServer } from "./server.js";
+export { WebhookConfigurationError, WebhookVerificationError } from "./errors.js";

package/dist/server/modules/webhooks-signature.d.ts

@@ -0,0 +1,11 @@
+import type { WebhookHeaders, WebhookPublicKeys } from "./webhooks.types.js";
+/** Split the configured keys into raw 32-byte Ed25519 keys. A truncated paste throws: a wrong key reads as every event being forged. */
+export declare function parsePublicKeys(keys: WebhookPublicKeys | undefined): Uint8Array[];
+export declare function importPublicKey(raw: Uint8Array): Promise<CryptoKey>;
+/** Read one header from a `Headers` or a Node-style object. */
+export declare function readHeader(headers: WebhookHeaders, name: string, separator?: string): string | null;
+/** The `v1a,<base64>` entries of a `webhook-signature` header, decoded. */
+export declare function parseSignatures(header: string): Uint8Array[];
+/** The signed bytes: `<id>.<timestamp>.<raw body>`. */
+export declare function signedPayload(id: string, timestamp: string, body: string | Uint8Array): Uint8Array;
+export declare function anySignatureVerifies(keys: CryptoKey[], signatures: Uint8Array[], payload: Uint8Array): Promise<boolean>;

package/dist/server/modules/webhooks-signature.js

@@ -0,0 +1,65 @@
+import { WebhookConfigurationError } from "../errors.js";
+const SIGNATURE_SCHEME = "v1a";
+const encoder = new TextEncoder();
+/** Standard base64 to bytes, or `null` when it is not valid base64. */
+function decodeBase64(value) {
+    try {
+        const binary = atob(value);
+        return Uint8Array.from(binary, char => char.charCodeAt(0));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** Split the configured keys into raw 32-byte Ed25519 keys. A truncated paste throws: a wrong key reads as every event being forged. */
+export function parsePublicKeys(keys) {
+    const entries = (Array.isArray(keys) ? keys : (keys !== null && keys !== void 0 ? keys : "").split(/[\s,]+/)).map(key => key.trim()).filter(Boolean);
+    if (entries.length === 0)
+        throw new WebhookConfigurationError("missing_public_keys", "no public keys were provided");
+    return entries.map(entry => {
+        const raw = decodeBase64(entry.replace(/^whpk_/, ""));
+        if (!raw || raw.length !== 32) {
+            throw new WebhookConfigurationError("invalid_public_key", "a public key is not a base64-encoded 32-byte Ed25519 key");
+        }
+        return raw;
+    });
+}
+export function importPublicKey(raw) {
+    return crypto.subtle.importKey("raw", raw, "Ed25519", false, ["verify"]);
+}
+/** Read one header from a `Headers` or a Node-style object. */
+export function readHeader(headers, name, separator = ", ") {
+    if (typeof headers.get === "function")
+        return headers.get(name);
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && value !== undefined)
+            return Array.isArray(value) ? value.join(separator) : value;
+    }
+    return null;
+}
+/** The `v1a,<base64>` entries of a `webhook-signature` header, decoded. */
+export function parseSignatures(header) {
+    return header
+        .split(" ")
+        .filter(entry => entry.startsWith(`${SIGNATURE_SCHEME},`))
+        .map(entry => decodeBase64(entry.slice(SIGNATURE_SCHEME.length + 1)))
+        .filter((signature) => signature !== null);
+}
+/** The signed bytes: `<id>.<timestamp>.<raw body>`. */
+export function signedPayload(id, timestamp, body) {
+    const prefix = encoder.encode(`${id}.${timestamp}.`);
+    const bytes = typeof body === "string" ? encoder.encode(body) : body;
+    const payload = new Uint8Array(prefix.length + bytes.length);
+    payload.set(prefix);
+    payload.set(bytes, prefix.length);
+    return payload;
+}
+export async function anySignatureVerifies(keys, signatures, payload) {
+    for (const key of keys) {
+        for (const signature of signatures) {
+            if (await crypto.subtle.verify("Ed25519", key, signature, payload))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/server/modules/webhooks.d.ts

@@ -0,0 +1,3 @@
+import type { WebhooksModule, WebhooksOptions } from "./webhooks.types.js";
+/** Webhook receiving utilities. Verification is local: no network calls, no timers. */
+export declare function createWebhooks(options?: WebhooksOptions): WebhooksModule;

package/dist/server/modules/webhooks.events.generated.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The `data` object of `app.created.v1`. An app was created.
+ */
+export interface AppCreatedV1Data {
+    /**
+     * The app the event is about.
+     */
+    app_id: string;
+    /**
+     * The workspace the app belongs to.
+     */
+    workspace_id: string;
+    /**
+     * Opaque platform id of the app's current owner.
+     */
+    owner_id: string;
+    /**
+     * Your own handle for the owner: the `service_external_id` you gave when you created that service user. Absent when the owner is not a service user.
+     */
+    owner_service_external_id?: string;
+    /**
+     * The kind of app. New values arrive as a new event version.
+     */
+    app_type: "imported_app" | "user_agent" | "user_app" | "user_game";
+    /**
+     * When the app was created (UTC).
+     */
+    created_at: string;
+}
+/**
+ * The `data` object of `app.published.v1`. An app version was published.
+ */
+export interface AppPublishedV1Data {
+    /**
+     * The app the event is about.
+     */
+    app_id: string;
+    /**
+     * The workspace the app belongs to.
+     */
+    workspace_id: string;
+    /**
+     * Opaque platform id of the app's current owner.
+     */
+    owner_id: string;
+    /**
+     * Your own handle for the owner: the `service_external_id` you gave when you created that service user. Absent when the owner is not a service user.
+     */
+    owner_service_external_id?: string;
+    /**
+     * Id of the version now live.
+     */
+    published_version: string;
+    /**
+     * When the version went live (UTC).
+     */
+    published_at: string;
+}
+/**
+ * The `data` object of `app.unpublished.v1`. An app was taken offline.
+ */
+export interface AppUnpublishedV1Data {
+    /**
+     * The app the event is about.
+     */
+    app_id: string;
+    /**
+     * The workspace the app belongs to.
+     */
+    workspace_id: string;
+    /**
+     * Opaque platform id of the app's current owner.
+     */
+    owner_id: string;
+    /**
+     * Your own handle for the owner: the `service_external_id` you gave when you created that service user. Absent when the owner is not a service user.
+     */
+    owner_service_external_id?: string;
+    /**
+     * When the app was taken offline (UTC).
+     */
+    unpublished_at: string;
+}
+/**
+ * Tombstone identifiers only.
+ *
+ * Deletion is **not** erasure: the app moves to trash and is self-serve
+ * restorable for 30 days, with unbounded restore through support. A receiver
+ * that purges on this event will be wrong for every restored app, which is why
+ * ``app.restored.v1`` exists and why this is documented as a trash signal.
+ */
+export interface AppDeletedV1Data {
+    /**
+     * The app the event is about.
+     */
+    app_id: string;
+    /**
+     * The workspace the app belongs to.
+     */
+    workspace_id: string;
+    /**
+     * Opaque platform id of the app's current owner.
+     */
+    owner_id: string;
+    /**
+     * Your own handle for the owner: the `service_external_id` you gave when you created that service user. Absent when the owner is not a service user.
+     */
+    owner_service_external_id?: string;
+    /**
+     * When the app was moved to trash (UTC). It can still be restored.
+     */
+    deleted_at: string;
+}
+/**
+ * The `data` object of `app.restored.v1`. An app was restored from trash.
+ */
+export interface AppRestoredV1Data {
+    /**
+     * The app the event is about.
+     */
+    app_id: string;
+    /**
+     * The workspace the app belongs to.
+     */
+    workspace_id: string;
+    /**
+     * Opaque platform id of the app's current owner.
+     */
+    owner_id: string;
+    /**
+     * Your own handle for the owner: the `service_external_id` you gave when you created that service user. Absent when the owner is not a service user.
+     */
+    owner_service_external_id?: string;
+    /**
+     * When the app was restored (UTC).
+     */
+    restored_at: string;
+}
+/**
+ * Carries no domain data — its only job is to be verifiable and echoed.
+ */
+export interface WebhookTestV1Data {
+    /**
+     * The endpoint being activated.
+     */
+    endpoint_id: string;
+    /**
+     * The workspace the endpoint belongs to.
+     */
+    workspace_id: string;
+    /**
+     * When the test was sent (UTC).
+     */
+    sent_at: string;
+    /**
+     * Return this value in your response body to activate the endpoint.
+     */
+    challenge: string;
+}
+/** Every event type Base44 sends, mapped to the shape of its `data` object. */
+export interface WebhookEventMap {
+    /** An app was created. */
+    "app.created.v1": AppCreatedV1Data;
+    /** An app version was published. */
+    "app.published.v1": AppPublishedV1Data;
+    /** An app was taken offline. */
+    "app.unpublished.v1": AppUnpublishedV1Data;
+    /** Tombstone identifiers only. */
+    "app.deleted.v1": AppDeletedV1Data;
+    /** An app was restored from trash. */
+    "app.restored.v1": AppRestoredV1Data;
+    /** Carries no domain data — its only job is to be verifiable and echoed. */
+    "webhook.test.v1": WebhookTestV1Data;
+}

package/dist/server/modules/webhooks.events.generated.js

@@ -0,0 +1,3 @@
+// Generated by scripts/generate-webhook-types.mjs from the schemas published at
+// https://base44.com/webhooks/schemas. Do not edit by hand; run `npm run generate:webhooks`.
+export {};

package/dist/server/modules/webhooks.js

@@ -0,0 +1,77 @@
+import { WebhookConfigurationError, WebhookVerificationError } from "../errors.js";
+import { anySignatureVerifies, importPublicKey, parsePublicKeys, parseSignatures, readHeader, signedPayload } from "./webhooks-signature.js";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Webhook receiving utilities. Verification is local: no network calls, no timers. */
+export function createWebhooks(options = {}) {
+    // Imported keys are cached by their wire form so a pinned key is imported once.
+    const imported = new Map();
+    const keysFor = (publicKeys = options.publicKeys) => Promise.all(parsePublicKeys(publicKeys).map(raw => {
+        const id = raw.join(",");
+        if (!imported.has(id))
+            imported.set(id, importPublicKey(raw));
+        return imported.get(id);
+    }));
+    const verifyEvent = async (body, headers, verifyOptions = {}) => {
+        var _a;
+        // Configuration problems surface first, whatever the request looks like: a missing key is ours to fix.
+        const keys = await keysFor(verifyOptions.publicKeys);
+        const id = readHeader(headers, "webhook-id");
+        const timestamp = readHeader(headers, "webhook-timestamp");
+        const signature = readHeader(headers, "webhook-signature", " ");
+        if (!id || !timestamp || !signature)
+            throw new WebhookVerificationError("missing_headers");
+        // Negated so a non-numeric timestamp (NaN) is refused too.
+        if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= ((_a = verifyOptions.toleranceSeconds) !== null && _a !== void 0 ? _a : DEFAULT_TOLERANCE_SECONDS))) {
+            throw new WebhookVerificationError("timestamp_outside_tolerance");
+        }
+        const signatures = parseSignatures(signature);
+        if (signatures.length === 0)
+            throw new WebhookVerificationError("no_signature_entries");
+        if (!(await anySignatureVerifies(keys, signatures, signedPayload(id, timestamp, body)))) {
+            throw new WebhookVerificationError("signature_mismatch");
+        }
+        // Only now is the body trusted enough to parse.
+        let event;
+        try {
+            event = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
+        }
+        catch (_b) {
+            throw new WebhookVerificationError("invalid_payload");
+        }
+        const { type, id: eventId, data } = (event !== null && event !== void 0 ? event : {});
+        if (typeof type !== "string" || typeof eventId !== "string" || typeof data !== "object" || data === null) {
+            throw new WebhookVerificationError("invalid_payload");
+        }
+        return event;
+    };
+    return {
+        verifyEvent,
+        createHandler({ on = {}, onEvent, onSuccess, onError, ...verifyOptions } = {}) {
+            const fail = async (error, status, event) => {
+                var _a;
+                return (_a = (await (onError === null || onError === void 0 ? void 0 : onError(error, event)))) !== null && _a !== void 0 ? _a : Response.json({ error: error instanceof WebhookVerificationError ? error.code : error instanceof WebhookConfigurationError ? "receiver_misconfigured" : "handler_failed" }, { status });
+            };
+            return async (request) => {
+                var _a, _b;
+                let event;
+                try {
+                    event = await verifyEvent(new Uint8Array(await request.arrayBuffer()), request.headers, verifyOptions);
+                }
+                catch (error) {
+                    return fail(error, error instanceof WebhookVerificationError ? 400 : 500);
+                }
+                // Activation probe: echo the challenge, only after the signature verified. Never reaches your callbacks.
+                if (event.type === "webhook.test.v1")
+                    return Response.json({ challenge: event.data.challenge });
+                try {
+                    await (onEvent === null || onEvent === void 0 ? void 0 : onEvent(event));
+                    await ((_a = on[event.type]) === null || _a === void 0 ? void 0 : _a.call(on, event));
+                    return (_b = (await (onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess(event)))) !== null && _b !== void 0 ? _b : new Response(null, { status: 204 });
+                }
+                catch (error) {
+                    return fail(error, 500, event);
+                }
+            };
+        },
+    };
+}

package/dist/server/modules/webhooks.types.d.ts

@@ -0,0 +1,102 @@
+import type { WebhookEventMap, WebhookTestV1Data } from "./webhooks.events.generated.js";
+export type * from "./webhooks.events.generated.js";
+/** Name of a webhook event, e.g. `app.deleted.v1`. */
+export type WebhookEventType = keyof WebhookEventMap;
+/** CloudEvents 1.0 envelope every Base44 webhook is delivered in. */
+export interface CloudEvent<TType extends string, TData> {
+    /** CloudEvents version. Always `1.0`. */
+    specversion: "1.0";
+    /** Unique event id (`evt_…`). Identical across redeliveries, so use it to deduplicate. */
+    id: string;
+    /** The workspace the event happened in, as a URL. */
+    source: string;
+    /** Event type, including its version. */
+    type: TType;
+    /** The resource the event is about, e.g. `apps/<app id>`. */
+    subject: string;
+    /** When the event occurred (RFC 3339, UTC). */
+    time: string;
+    /** Content type of `data`. Always `application/json`. */
+    datacontenttype: string;
+    /** URL of the JSON Schema describing `data`. */
+    dataschema: string;
+    /** W3C trace context, when the event was produced inside a trace. */
+    traceparent?: string;
+    /** W3C trace state, when present. */
+    tracestate?: string;
+    /** Kind of actor that caused the event. */
+    authtype: string;
+    /** Identifier of the actor that caused the event. */
+    authid: string;
+    /** Event-specific payload. */
+    data: TData;
+}
+/**
+ * A verified Base44 webhook event. Narrow on `type` to read `data`.
+ * Base44 may add event types later, so give a `switch` a default branch that still answers 2xx.
+ */
+export type WebhookEvent = {
+    [K in WebhookEventType]: CloudEvent<K, WebhookEventMap[K]>;
+}[WebhookEventType];
+/** Request headers in any common shape: a fetch `Headers`, or a Node-style object. Names are case-insensitive. */
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+/** One Ed25519 public key (`whpk_…`), or several separated by commas or whitespace. */
+export type WebhookPublicKeys = string | string[];
+/** Webhook settings for `createBase44PlatformServer`. */
+export interface WebhooksOptions {
+    /** Public keys of your workspace. Pass more than one while a key rotation is in progress. */
+    publicKeys?: WebhookPublicKeys;
+}
+/** Per-call overrides for `verifyEvent`. */
+export interface VerifyEventOptions {
+    /** Public keys to verify against, instead of the ones the client was created with. */
+    publicKeys?: WebhookPublicKeys;
+    /** Maximum age or clock skew of a delivery, in seconds. Defaults to 300. */
+    toleranceSeconds?: number;
+}
+/** An event your handler receives: every event except the `webhook.test.v1` probe, which `createHandler` answers itself. */
+export type DeliveredWebhookEvent = Exclude<WebhookEvent, CloudEvent<"webhook.test.v1", WebhookTestV1Data>>;
+/** Per-type handlers for `createHandler`, each receiving the event already narrowed to its type. */
+export type WebhookEventHandlers = {
+    [K in DeliveredWebhookEvent["type"]]?: (event: Extract<DeliveredWebhookEvent, {
+        type: K;
+    }>) => unknown;
+};
+/** Options for `createHandler`. Every callback may be async. */
+export interface CreateHandlerOptions extends VerifyEventOptions {
+    /** Handlers keyed by event type. Types without a handler are still answered 2xx, so Base44 does not retry them. */
+    on?: WebhookEventHandlers;
+    /** Called for every verified event, before its handler in `on`. */
+    onEvent?: (event: DeliveredWebhookEvent) => unknown;
+    /**
+     * Called once `onEvent` and the event's handler finished without throwing. Return a `Response` to replace the default
+     * empty 204.
+     */
+    onSuccess?: (event: DeliveredWebhookEvent) => Response | void | Promise<Response | void>;
+    /**
+     * Called when a delivery fails: a `WebhookVerificationError` (default response 400), a
+     * `WebhookConfigurationError` (500), or whatever a handler threw (500, so Base44 retries). `event`
+     * is set when verification passed and a callback failed. Return a `Response` to replace the default.
+     */
+    onError?: (error: unknown, event?: DeliveredWebhookEvent) => Response | void | Promise<Response | void>;
+}
+/** Receive and verify Base44 outbound webhooks. Makes no network requests. */
+export interface WebhooksModule {
+    /**
+     * Verify a delivery and return the event.
+     *
+     * Pass the body exactly as received, before any JSON parsing. Nothing is parsed until the
+     * signature checks out. Rejects with `WebhookVerificationError` for a delivery you should
+     * refuse (respond 400) and `WebhookConfigurationError` when the public keys are missing
+     * or malformed (let it surface as a 500 so Base44 retries). To activate an endpoint, answer
+     * the `webhook.test.v1` event with `{ "challenge": event.data.challenge }`.
+     */
+    verifyEvent(body: string | Uint8Array, headers: WebhookHeaders, options?: VerifyEventOptions): Promise<WebhookEvent>;
+    /**
+     * Build a fetch-style route handler (`(request: Request) => Promise<Response>`) for Next.js, Hono,
+     * Cloudflare Workers, Deno or Bun. It reads the raw body, verifies it, answers the activation
+     * challenge, then runs your callbacks. Delivery is at least once, so handlers must tolerate
+     * the same event (same `event.id`) arriving twice.
+     */
+    createHandler(options?: CreateHandlerOptions): (request: Request) => Promise<Response>;
+}

package/dist/server/modules/webhooks.types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/server.d.ts

@@ -1,7 +1,3 @@
-import type { PlatformServerOptions } from "./server.types.js";
-/** Server platform client, authenticated with a workspace API key. Construction performs no network requests. */
-export declare class Base44PlatformServer {
-    #private;
-    /** Configure shared service/auth settings; modules are added on top of this. */
-    constructor(options: PlatformServerOptions);
-}
+import type { Base44PlatformServer, PlatformServerOptions } from "./server.types.js";
+/** Create a server platform client, authenticated with a workspace API key. Performs no network requests. */
+export declare function createBase44PlatformServer(options: PlatformServerOptions): Base44PlatformServer;

package/dist/server/server.js

@@ -1,21 +1,11 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var _Base44PlatformServer_serverUrl, _Base44PlatformServer_apiKey;
 import { normalizeServerUrl } from "../shared/server-url.js";
-/** Server platform client, authenticated with a workspace API key. Construction performs no network requests. */
-export class Base44PlatformServer {
-    /** Configure shared service/auth settings; modules are added on top of this. */
-    constructor(options) {
-        _Base44PlatformServer_serverUrl.set(this, void 0);
-        _Base44PlatformServer_apiKey.set(this, void 0);
-        if (!options.apiKey)
-            throw new TypeError("apiKey is required");
-        __classPrivateFieldSet(this, _Base44PlatformServer_serverUrl, normalizeServerUrl(options.serverUrl), "f");
-        __classPrivateFieldSet(this, _Base44PlatformServer_apiKey, options.apiKey, "f");
-    }
+import { createWebhooks } from "./modules/webhooks.js";
+/** Create a server platform client, authenticated with a workspace API key. Performs no network requests. */
+export function createBase44PlatformServer(options) {
+    if (!options.apiKey)
+        throw new TypeError("apiKey is required");
+    normalizeServerUrl(options.serverUrl);
+    return Object.freeze({
+        webhooks: Object.freeze(createWebhooks(options.webhooks)),
+    });
 }
-_Base44PlatformServer_serverUrl = new WeakMap(), _Base44PlatformServer_apiKey = new WeakMap();

package/dist/server/server.types.d.ts

@@ -1,7 +1,15 @@
+import type { WebhooksModule, WebhooksOptions } from "./modules/webhooks.types.js";
 /** Shared configuration for server platform modules. */
 export interface PlatformServerOptions {
     /** Origin of the platform service, e.g. https://base44.app. No path/query/credentials. */
     serverUrl: string;
     /** Workspace API key. Keep it on your server; never ship it to a browser. */
     apiKey: string;
+    /** Webhook receiving settings. */
+    webhooks?: WebhooksOptions;
+}
+/** Server platform client, returned by `createBase44PlatformServer`. */
+export interface Base44PlatformServer {
+    /** Verify Base44 outbound webhooks and answer the activation challenge. */
+    readonly webhooks: WebhooksModule;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/platform",
-  "version": "0.1.0-pr.316.56344d6",
+  "version": "0.1.0-pr.319.1e807d1",
   "description": "Client and server SDK for building on the Base44 platform",
   "main": "dist/client/index.js",
   "types": "dist/client/index.d.ts",
@@ -29,7 +29,8 @@
     "test:types": "tsc --noEmit -p tsconfig.type-tests.json",
     "test:unit": "vitest run",
     "test:package": "npm run build && node --test tests/package.test.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "generate:webhooks": "node scripts/generate-webhook-types.mjs"
   },
   "dependencies": {
     "socket.io-client": "^4.8.3"
@@ -56,5 +57,11 @@
         "dist/server/index.d.ts"
       ]
     }
+  },
+  "devDependencies": {
+    "json-schema-to-typescript": "^16.0.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }