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

package/dist/client/modules/builder.events.types.d.ts

@@ -0,0 +1,368 @@
+/** Activity a file, execution or entity tool declared public. */
+export interface ToolDisplay {
+    /** Changed file paths for a file operation. Source bodies and diffs are never included. */
+    file_paths?: string[];
+    /** Whether a file write intentionally used empty content. */
+    content_empty?: boolean;
+    /** Reviewed execution activity summary. Commands and execution output are never included. */
+    summary?: string;
+    /** Whether a reviewed execution action changed entity data. */
+    writes_entities?: boolean;
+    /** Entity type affected by an entity operation. Records and query values are never included. */
+    entity_name?: string;
+    /** Number of records affected when supplied by the producer. */
+    record_count?: number;
+}
+/** A selectable answer to a builder question. */
+export interface ToolQuestionOption {
+    /** Visible option label. */
+    label?: string;
+}
+/** A builder question. Image/HTML source and private design context are excluded. */
+export interface ToolQuestion {
+    /** Visible question text. */
+    question?: string;
+    /** Question category. */
+    type?: string;
+    /** Optional visible supporting text. */
+    description?: string;
+    /** Whether more than one answer may be selected. */
+    multi_select?: boolean;
+    /** Plan section the question covers. */
+    covers?: string;
+    /** Selectable options; a bare string option is its label. */
+    options?: (ToolQuestionOption | string)[];
+}
+/** `ask_clarifying_questions` and `ask_plan_questions` arguments. */
+export interface ToolQuestionArguments {
+    /** Questions presented to the user. */
+    questions?: ToolQuestion[];
+}
+/** A requested secret field. The secret value is never sent over the socket. */
+export interface ToolSecretField {
+    /** Requested secret name. */
+    secretName?: string;
+    /** Optional explanation of where to obtain it. */
+    description?: string;
+}
+/** `set_secrets` arguments. */
+export interface ToolSecretArguments {
+    /** Requested secret fields. */
+    secrets_schema?: ToolSecretField[];
+}
+/** A package operation. Versions and package-manager output are excluded. */
+export interface ToolPackageOperation {
+    /** Package name. */
+    name?: string;
+    /** Requested package operation. */
+    action?: string;
+}
+/** `install_npm_package` arguments. */
+export interface ToolPackageArguments {
+    /** Requested package operations. */
+    packages?: ToolPackageOperation[];
+}
+/** An add-only builder plan update. */
+export interface ToolPlanUpdate {
+    /** Update action. */
+    action?: string;
+    /** Plan section key. */
+    section?: string;
+    /** Optional user-facing section label. */
+    section_label?: string;
+    /** Plan point. */
+    text?: string;
+}
+/** `update_plan` arguments. */
+export interface ToolPlanArguments {
+    /** Plan updates in their emitted order. */
+    updates?: ToolPlanUpdate[];
+    /** Base plan sections the builder considers sufficiently specified. */
+    sections_with_enough?: string[];
+}
+/** `generate_prd` arguments: the user's own plan. In plan mode the message `content` beside it can be empty. */
+export interface ToolPrdArguments {
+    /** App or feature name. */
+    app_name?: string;
+    /** What is being built and why. */
+    intent_and_goal?: string;
+    /** Who uses it and their roles. */
+    audience_and_roles?: string;
+    /** End-to-end user flows. */
+    core_flows?: string[];
+    /** Specific technical requirements. */
+    technical_requirements?: string;
+    /** Design preferences. */
+    design_preferences?: string;
+    /** Build or plan declaration, when the builder asks for one. */
+    prd_type?: string;
+    /** Store platform settled in planning, for e-commerce plans. */
+    store_platform?: string;
+    /** Engine settled in planning, for game plans. */
+    game_engine?: string;
+}
+/** Image, game-image and video generation arguments. */
+export interface ToolMediaArguments {
+    /** Visible media label. */
+    label?: string;
+    /** Requested image or video aspect ratio. */
+    aspect_ratio?: string;
+}
+/** `update_entities` and `delete_entities` arguments; the entity is in `display.entity_name`. */
+export interface ToolEntityMutationArguments {
+    /** The agent's summary of the change. Queries and record values are never included. */
+    summary?: string;
+}
+/** The public arguments of a tool that declares them; narrow by the tool call's `name`. */
+export type ToolArguments = ToolQuestionArguments | ToolSecretArguments | ToolPackageArguments | ToolPlanArguments | ToolPrdArguments | ToolMediaArguments | ToolEntityMutationArguments;
+/** Generated-media state. Raw generation prompts and IDs are never included. */
+export interface ToolMediaResult {
+    /** Placeholder URL, used to associate an `image.resolved` event with this tool. */
+    placeholder_url?: string;
+    /** Current media-generation status. */
+    status?: "pending" | "completed" | "failed";
+    /** Generated asset URL, once available. */
+    image_url?: string | null;
+}
+/** An answer to a clarifying question. Secret-form input is never included. */
+export interface ToolQuestionAnswer {
+    /** Zero-based question index. */
+    question_index?: number;
+    /** Label selected for a single-select question. */
+    selected_label?: string;
+    /** Labels selected for a multi-select question. */
+    selected_labels?: string[];
+    /** User-provided free-text answer. Structural filtering does not redact prose. */
+    custom_text?: string;
+}
+/** Clarifying-question answers. */
+export interface ToolQuestionInput {
+    /** Answers supplied to the question card. */
+    answers?: ToolQuestionAnswer[];
+}
+/** Why a safety guard parked a call for approval. Only present while the call waits. */
+export interface ToolGuardApproval {
+    /** Guard identifier, e.g. `exec_tool_send_email` or `bash_approval`. */
+    guard: string;
+    /** Human-readable reason, for guards whose reason never quotes input (not shell commands). */
+    reason?: string;
+    /** The details the guard declares public; commands and record data are never included. */
+    details?: {
+        /** Entity method the code calls, e.g. `delete`. */
+        method?: string;
+        /** The agent's summary of what the code does. */
+        summary?: string;
+        /** Entity whose access rules change. */
+        entity_name?: string;
+        /** How the access rules change. */
+        change_type?: string;
+        /** Access operations whose rules change. */
+        changed_ops?: string[];
+        /** Backend function under test. */
+        function_name?: string;
+        /** The guard could not verify the function's source. */
+        inspection_failed?: boolean;
+    };
+}
+/** Public progress of a builder tool call. Only what the tool and its guard declare public is present. */
+export interface ToolCall {
+    /** Stable tool call identifier. */
+    id?: string;
+    /** Tool name. */
+    name?: string;
+    /** Current execution state. */
+    status?: "running" | "success" | "error" | "stopped" | "waiting_for_user_input";
+    /** Whether the tool needs a user response through the partner backend. */
+    requires_user_input?: boolean;
+    /** Whether the builder auto-approved the operation. */
+    auto_approved?: boolean;
+    /** Whether the mutation was applied. */
+    mutation_applied?: boolean | null;
+    /** Kind of response a parked call waits for. */
+    waiting_on?: {
+        /** Kind of response expected. */
+        kind?: "approval" | "choice" | "input";
+    };
+    /** The tool's public arguments; absent for tools that declare none and for partial streaming arguments. */
+    arguments?: ToolArguments;
+    /** What a file, execution or entity tool touched. */
+    display?: ToolDisplay;
+    /** Clarifying-question answers. */
+    user_input?: ToolQuestionInput;
+    /** Generated media, once the call is not waiting on a guard: the image tool's state, or a URL alone
+     * (a game asset's placeholder, which `image.resolved` replaces, or a finished video). */
+    results?: ToolMediaResult | string;
+    /** A parked call's guard, and its reason and details where the guard declares them. */
+    approval?: ToolGuardApproval;
+}
+/** Scalar parameters a chat UI needs while a turn runs. */
+export interface MessageParams {
+    /** Identifier the sending client attached, to match its optimistic message. */
+    client_creation_id?: string;
+    /** The message was sent in plan mode. */
+    plan_mode?: boolean;
+    /** The message approves a plan. */
+    plan_approved?: boolean;
+    /** The message expects no AI reply. */
+    skip_ai_response?: boolean;
+    /** System message category. */
+    system_message_type?: string;
+}
+/** A public chat message. Replace the message with the same `id` as a whole. */
+export interface ChatMessage {
+    /** Message identifier. */
+    id?: string;
+    /** Author category. System and hidden messages are never delivered. */
+    role?: "user" | "assistant";
+    /** Message text; structured content is withheld. Structural filtering is not prose redaction. */
+    content?: string | null;
+    /** Public tool progress. */
+    tool_calls?: ToolCall[] | null;
+    /** Message timestamp, without author identity. */
+    metadata?: {
+        /** ISO timestamp string. */
+        created_date?: string;
+    };
+    /** Checkpoint reference; mutations remain on the partner backend. */
+    checkpoint_id?: string | null;
+    /** Scalar message parameters. */
+    additional_message_params?: MessageParams;
+}
+/** Public builder state, without error diagnostics or billing context. */
+export interface AppStatus {
+    /** Current builder state. */
+    state?: "ready" | "processing" | "error";
+    /** State timestamp. */
+    last_updated_date?: string | null;
+    /** The user message that started the turn, when a turn set this state. Quote it to Base44 support. */
+    turn_id?: string | null;
+}
+/** Branch scope carried by app events. Null or absent is the main branch. */
+export interface BranchScoped {
+    /** Branch the change belongs to; null is main. */
+    branch_id?: string | null;
+}
+/** `message.updated`: a chat message was added or replaced. */
+export interface MessageUpdated extends BranchScoped {
+    /** The whole message; replace the one with the same `id`. */
+    message: ChatMessage;
+    /** Conversation containing the message. */
+    conversation_id?: string | null;
+}
+/** `message.removed`: a message was removed or hidden. An `id` the viewer never saw is a no-op. */
+export interface MessageRemoved extends BranchScoped {
+    /** Identifier of the message to remove. */
+    message_id: string;
+    /** Conversation that contained the message. */
+    conversation_id?: string | null;
+}
+/** `app.status_changed`: a turn started, finished or failed. */
+export interface AppStatusChanged extends BranchScoped {
+    /** The new state; null clears it. */
+    status: AppStatus | null;
+}
+/** `preview.navigation_requested`: show this page of the app in the preview. */
+export interface PreviewNavigationRequested extends BranchScoped {
+    /** App path to show. */
+    path: string;
+    /** Navigate even when the user has moved away from the page. */
+    force: boolean;
+}
+/** A queued builder request. */
+export interface QueueItem {
+    /** Queue item identifier. */
+    id?: string;
+    /** User-authored request text. */
+    content?: string;
+    /** Creation timestamp. */
+    created_at?: string;
+    /** Branch the request belongs to. */
+    branch_id?: string | null;
+}
+/** `queue.updated`: the whole prompt queue, replacing the previous one. */
+export interface QueueUpdated extends BranchScoped {
+    /** Pending items. */
+    items?: QueueItem[];
+    /** Whether queue processing is paused. */
+    is_paused?: boolean;
+    /** Identifier of the item just processed, when supplied. */
+    processed_item_id?: string | null;
+}
+/** `task.progressed`: progress of a long-running tool. */
+export interface TaskProgressed extends BranchScoped {
+    /** Associated tool call. */
+    tool_call_id?: string | null;
+    /** Associated chat message. */
+    message_id?: string | null;
+    /** Task lifecycle event, e.g. `task_progress`. */
+    event_type?: string | null;
+    /** Numeric progress only; diagnostic text is withheld. */
+    progress?: {
+        /** Completed work units. */
+        current?: number | null;
+        /** Total work units, when known. */
+        total?: number | null;
+        /** Producer-supplied percentage. */
+        percentage?: number | null;
+    } | null;
+}
+/** `image.resolved`: a generated image finished or failed. Replace its `placeholder_url` wherever it appears. */
+export type ImageResolved = ToolMediaResult;
+/** Mapping of public event names to their payloads. */
+export interface PlatformEventMap {
+    /** A chat message was added or replaced. */
+    "message.updated": MessageUpdated;
+    /** A chat message was removed or hidden. */
+    "message.removed": MessageRemoved;
+    /** The builder started, finished or failed a turn. */
+    "app.status_changed": AppStatusChanged;
+    /** Reload the app preview. */
+    "preview.reload_requested": BranchScoped;
+    /** Show a page of the app in the preview. */
+    "preview.navigation_requested": PreviewNavigationRequested;
+    /** The whole prompt queue. */
+    "queue.updated": QueueUpdated;
+    /** Progress of a long-running tool. */
+    "task.progressed": TaskProgressed;
+    /** A generated image finished or failed. */
+    "image.resolved": ImageResolved;
+    /** The conversation was rewritten (undo, restore, sync). On main, the SDK rejoins for a fresh snapshot. */
+    "conversation.changed": BranchScoped;
+    /** The app's files changed outside a chat turn. Re-read them. */
+    "files.changed": BranchScoped;
+    /** A branch was deleted. */
+    "branch.deleted": BranchScoped;
+    /** The imported app's repository changed. */
+    "repository.changed": BranchScoped;
+    /** The imported app's pull request changed. */
+    "pull_request.changed": BranchScoped;
+}
+/** Ordered delivery of one public event. */
+export type PlatformEvent = {
+    [K in keyof PlatformEventMap]: {
+        /** Public event name; narrows the payload type. */
+        type: K;
+        /** Authorized app receiving this event. */
+        appId: string;
+        /** Event payload. Omitted keys mean unchanged; explicit null clears. */
+        data: PlatformEventMap[K];
+    };
+}[keyof PlatformEventMap];
+/** An app's current state: sent after every join and rejoin, and after a main-conversation rewrite. */
+export interface Snapshot {
+    /** Canonical app room. */
+    room: string;
+    /** Current builder state. */
+    status: AppStatus | null;
+    /** The last 50 public messages, oldest first. */
+    messages: ChatMessage[];
+    /** The main branch's prompt queue. Replace it, as with `queue.updated`. Absent from older servers. */
+    queue?: SnapshotQueue;
+}
+/** The prompt queue in a snapshot. */
+export interface SnapshotQueue {
+    /** Pending items. */
+    items: QueueItem[];
+    /** Whether queue processing is paused. */
+    is_paused: boolean;
+}

package/dist/client/modules/builder.events.types.js

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

package/dist/client/modules/builder.js

@@ -0,0 +1,7 @@
+import { BuilderSocket } from "./builder-socket.js";
+/** @internal */
+export function createBuilder(config) {
+    return {
+        init(options) { return new BuilderSocket(config, options); },
+    };
+}

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

@@ -0,0 +1,47 @@
+import type { PlatformEvent, Snapshot } from "./builder.events.types.js";
+import type { PlatformSocketError } from "../errors.js";
+/** Options for an independent builder socket session. */
+export interface BuilderInitOptions {
+    /** Connection-level errors, sanitized to exclude tokens and server exception text. */
+    onError: (error: PlatformSocketError) => void;
+}
+/** Lazy builder module; no socket exists until init is called. */
+export interface BuilderModule {
+    /** Create an independent session without connecting. Call connect on the returned session. */
+    init(options: BuilderInitOptions): BuilderSession;
+}
+/** One builder socket session. Owns its subscriptions and connection lifecycle. */
+export interface BuilderSession {
+    /** Connect with the session token; resolves on CONNECT, before snapshots arrive.
+     * Transport loss retries five times and rejoins active subscriptions, each with a fresh
+     * snapshot. An expired or rejected session is replaced once through `getSessionToken`.
+     * Call again after a failure or `session_replaced`. Concurrent calls share one attempt.
+     */
+    connect(): Promise<void>;
+    /** Subscribe before or after connecting. One subscription per app, up to eight per session,
+     * and each app must be on the session's allowlist. Callbacks run serially per app.
+     */
+    subscribe(appId: string, options: SubscriptionOptions): PlatformSubscription;
+    /** Stop this session, its subscriptions and reconnection. Idempotent and terminal. */
+    close(): void;
+}
+/** One app subscription; at most eight may be active per builder session. */
+export interface SubscriptionOptions {
+    /** Replace this app's state. Arrives after every join and rejoin, and after a main-conversation
+     * rewrite (undo, restore, sync). Live events follow it; it holds only the last 50 messages.
+     */
+    onSnapshot: (snapshot: Snapshot) => void | Promise<void>;
+    /** Apply each live event. Delivery is serial per app; a rejection ends this subscription. */
+    onEvent: (event: PlatformEvent) => void | Promise<void>;
+    /** Subscription errors. Only `snapshot_unavailable` leaves the subscription active. */
+    onError: (error: PlatformSocketError) => void;
+}
+/** One app subscription's lifetime. */
+export interface PlatformSubscription {
+    /** App identifier. */
+    readonly appId: string;
+    /** True while subscribed; false after an error or explicit unsubscribe. */
+    readonly active: boolean;
+    /** Stop this app's delivery and release its subscription slot. Idempotent. */
+    unsubscribe(): void;
+}

package/dist/client/modules/builder.types.js

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

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

@@ -0,0 +1,6 @@
+/** Server platform modules, authenticated with a workspace API key. */
+export { Base44PlatformServer } from "./server.js";
+export { WebhookConfigurationError, WebhookVerificationError } from "./errors.js";
+export type { WebhookConfigurationErrorCode, WebhookVerificationErrorCode } from "./errors.types.js";
+export type { 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

@@ -0,0 +1,3 @@
+/** Server platform modules, authenticated with a workspace API key. */
+export { Base44PlatformServer } 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;