@base44-preview/platform 0.0.0 → 0.1.0-pr.319.850fe58

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 {@link Base44PlatformServer}. */
+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

@@ -0,0 +1,10 @@
+import type { WebhooksModule } from "./modules/webhooks.types.js";
+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;
+    /** Verify Base44 outbound webhooks and answer the activation challenge. */
+    readonly webhooks: WebhooksModule;
+    /** Configure shared service/auth settings; modules are added on top of this. */
+    constructor(options: PlatformServerOptions);
+}

package/dist/server/server.js

@@ -0,0 +1,23 @@
+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";
+import { createWebhooks } from "./modules/webhooks.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");
+        this.webhooks = Object.freeze(createWebhooks(options.webhooks));
+    }
+}
+_Base44PlatformServer_serverUrl = new WeakMap(), _Base44PlatformServer_apiKey = new WeakMap();

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

@@ -0,0 +1,10 @@
+import type { 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;
+}

package/dist/server/server.types.js

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

package/dist/shared/server-url.d.ts

@@ -0,0 +1,2 @@
+/** Validate a platform origin and return it normalized. Shared by the client and server entrypoints. */
+export declare function normalizeServerUrl(serverUrl: string): string;

package/dist/shared/server-url.js

@@ -0,0 +1,8 @@
+/** Validate a platform origin and return it normalized. Shared by the client and server entrypoints. */
+export function normalizeServerUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+        throw new TypeError("serverUrl must be an HTTP(S) origin without credentials, path, query or fragment");
+    }
+    return url.origin;
+}

package/package.json

@@ -1,7 +1,67 @@
 {
   "name": "@base44-preview/platform",
-  "version": "0.0.0",
-  "description": "Preview builds of @base44/platform, published from PRs. Not for production use.",
+  "version": "0.1.0-pr.319.850fe58",
+  "description": "Client and server SDK for building on the Base44 platform",
+  "main": "dist/client/index.js",
+  "types": "dist/client/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "docs": "typedoc",
+    "test": "npm run test:types && npm run test:unit && npm run docs && npm run test:package",
+    "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",
+    "generate:webhooks": "node scripts/generate-webhook-types.mjs"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "keywords": [
+    "base44",
+    "platform",
+    "white-label"
+  ],
+  "author": "Base44",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/base44/javascript-sdk.git", "directory": "packages/platform" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/base44/javascript-sdk.git",
+    "directory": "packages/platform"
+  },
+  "bugs": {
+    "url": "https://github.com/base44/javascript-sdk/issues"
+  },
+  "homepage": "https://github.com/base44/javascript-sdk/tree/main/packages/platform#readme",
+  "typesVersions": {
+    "*": {
+      "server": [
+        "dist/server/index.d.ts"
+      ]
+    }
+  },
+  "devDependencies": {
+    "json-schema-to-typescript": "^16.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
 }