primitive-functions 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,20 @@
+# primitive-functions
+
+The module a [Primitive](https://primitive.dev) **server function** imports.
+
+```ts
+import { defineFunction } from "primitive-functions";
+
+export default defineFunction(async (input) => {
+  return { ok: true, echo: input };
+});
+```
+
+The platform supplies this module at invoke time: `primitive config push`
+builds your function's bundle with esbuild, inlines every npm dependency, and
+leaves `primitive-functions` external — so your function always runs against the SDK
+the platform is running.
+
+This release is a **name reservation** (issue #3179). Its runtime surface
+lands with the server-functions loader; calling anything here outside a
+Primitive sandbox throws.

package/index.d.ts

@@ -0,0 +1,706 @@
+// GENERATED by scripts/generate-function-profile.mjs from openapi.json.
+// DO NOT EDIT. Run `pnpm functions:profile` and commit the result; the
+// freshness guard in tests/api/spec/function-profile.test.ts fails when this
+// file and a fresh generation diverge.
+
+/**
+ * Type surface of `primitive-functions` — what a server function's author writes
+ * against (#3180). The published package's RUNTIME is a stub that throws from
+ * every export on purpose: the platform substitutes its own copy at invoke
+ * time, and reaching the stub means it did not.
+ */
+
+/** The signed-in user on whose behalf the invocation runs. */
+export interface FunctionUser {
+  userId: string;
+  email: string | null;
+}
+
+/** What started this invocation. Only `http` exists today. */
+export interface FunctionTrigger {
+  kind: "http";
+}
+
+/** The result shape of an operation that answers in response headers. */
+export interface HeaderResult {
+  status: number;
+  headers: Record<string, string>;
+}
+
+/**
+ * A platform call that was refused. `errorCode` carries the gateway's own
+ * codes (`FUNCTION_ROUTE_NOT_ALLOWED`, `FUNCTION_EGRESS_DENIED`, …) as well
+ * as the route's.
+ */
+export interface PrimitivePlatformError extends Error {
+  status: number;
+  errorCode: string | null;
+}
+
+/**
+ * The typed HTTP profile, generated from the platform's OpenAPI document. Its
+ * namespaces mirror the operation ids: databaseTypeConfigs, databases, documents, functions.
+ * Methods take one options object carrying the operation's path parameters,
+ * query parameters, request headers (under their wire names) and `body`.
+ *
+ * Generated from the same operations as the runtime profile, so a method that
+ * type-checks is a method the platform publishes — and a missing path
+ * parameter or a missing required header is a compile error rather than a
+ * `TypeError` at invoke time. Namespaces the GATEWAY does not yet allow are
+ * still declared: they exist, they answer the gateway's structured denial, and
+ * hiding them would make a route's availability look like a typo.
+ */
+export interface FunctionApi {
+  "databaseTypeConfigs": {
+    /** `databaseTypeConfigs.create` — POST /databases/types. Create a database type */
+    "create"(args: {
+      "dryRun"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.createOperation` — POST /databases/types/{databaseType}/operations. Create an operation for a database type */
+    "createOperation"(args: {
+      "databaseType": string | number;
+      "dryRun"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.delete` — DELETE /databases/types/{databaseType}. Delete a database type */
+    "delete"(args: {
+      "databaseType": string | number;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.deleteOperation` — DELETE /databases/types/{databaseType}/operations/{name}. Delete an operation for a database type */
+    "deleteOperation"(args: {
+      "databaseType": string | number;
+      "name": string | number;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.get` — GET /databases/types/{databaseType}. Get a database type */
+    "get"(args: {
+      "databaseType": string | number;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.getOperation` — GET /databases/types/{databaseType}/operations/{name}. Get an operation for a database type */
+    "getOperation"(args: {
+      "databaseType": string | number;
+      "name": string | number;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.getReindexStatus` — GET /databases/types/{databaseType}/reindex-status. Status of the index back-provision fan-out for a type */
+    "getReindexStatus"(args: {
+      "databaseType": string | number;
+      "runId"?: string | number | boolean;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.list` — GET /databases/types. List database types */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `databaseTypeConfigs.listOperations` — GET /databases/types/{databaseType}/operations. List operations for a database type */
+    "listOperations"(args: {
+      "databaseType": string | number;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.scaffoldSchema` — POST /databases/types/{databaseType}/schema:scaffold. Scaffold a starter schema for a database type */
+    "scaffoldSchema"(args: {
+      "databaseType": string | number;
+    }): Promise<any>;
+    "subscriptions": {
+      /** `databaseTypeConfigs.subscriptions.create` — POST /databases/types/{databaseType}/subscriptions. Create a subscription for a database type */
+      "create"(args: {
+        "databaseType": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databaseTypeConfigs.subscriptions.delete` — DELETE /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Delete a database type subscription */
+      "delete"(args: {
+        "databaseType": string | number;
+        "subscriptionKey": string | number;
+      }): Promise<any>;
+      /** `databaseTypeConfigs.subscriptions.get` — GET /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Get a database type subscription */
+      "get"(args: {
+        "databaseType": string | number;
+        "subscriptionKey": string | number;
+      }): Promise<any>;
+      /** `databaseTypeConfigs.subscriptions.list` — GET /databases/types/{databaseType}/subscriptions. List subscriptions for a database type */
+      "list"(args: {
+        "databaseType": string | number;
+      }): Promise<any>;
+      /** `databaseTypeConfigs.subscriptions.update` — PUT /databases/types/{databaseType}/subscriptions/{subscriptionKey}. Update a database type subscription */
+      "update"(args: {
+        "databaseType": string | number;
+        "subscriptionKey": string | number;
+        body: unknown;
+      }): Promise<any>;
+    };
+    /** `databaseTypeConfigs.update` — PATCH /databases/types/{databaseType}. Update a database type */
+    "update"(args: {
+      "databaseType": string | number;
+      "dryRun"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+    /** `databaseTypeConfigs.updateOperation` — PATCH /databases/types/{databaseType}/operations/{name}. Update an operation for a database type */
+    "updateOperation"(args: {
+      "databaseType": string | number;
+      "name": string | number;
+      "dryRun"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+  };
+  "databases": {
+    /** `databases.addManager` — PUT /databases/{databaseId}/permissions. Set a user's database permission */
+    "addManager"(args: {
+      "databaseId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    "adminData": {
+      /** `databases.adminData.batch` — POST /databases/{databaseId}/admin-data/batch. DEPRECATED — direct database batch; use databases/{databaseId}/records/batch */
+      "batch"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.adminData.count` — POST /databases/{databaseId}/admin-data/count. DEPRECATED — direct database count; use databases/{databaseId}/records/count */
+      "count"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.adminData.delete` — POST /databases/{databaseId}/admin-data/delete. DEPRECATED — direct database delete; use databases/{databaseId}/records/delete */
+      "delete"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.adminData.patch` — POST /databases/{databaseId}/admin-data/patch. DEPRECATED — direct database patch; use databases/{databaseId}/records/patch */
+      "patch"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.adminData.query` — POST /databases/{databaseId}/admin-data/query. DEPRECATED — direct database query; use databases/{databaseId}/records/query */
+      "query"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.adminData.save` — POST /databases/{databaseId}/admin-data/save. DEPRECATED — direct database save; use databases/{databaseId}/records/save */
+      "save"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+    };
+    /** `databases.create` — POST /databases. Create a database */
+    "create"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.delete` — DELETE /databases/{databaseId}. Delete a database */
+    "delete"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.executeBatch` — POST /databases/{databaseId}/operations/{name}/batch. Execute a database operation in batch */
+    "executeBatch"(args: {
+      "databaseId": string | number;
+      "name": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.executeOperation` — POST /databases/{databaseId}/operations/{name}/execute. Execute a database operation */
+    "executeOperation"(args: {
+      "databaseId": string | number;
+      "name": string | number;
+      "dryRun"?: string | number | boolean;
+      body?: unknown;
+    }): Promise<any>;
+    /** `databases.get` — GET /databases/{databaseId}. Get a database by id */
+    "get"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.getMetadata` — GET /databases/{databaseId}/metadata. Get database metadata */
+    "getMetadata"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.grantGroupPermission` — POST /databases/{databaseId}/group-permissions. Grant a group permission on a database */
+    "grantGroupPermission"(args: {
+      "databaseId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.importBulk` — POST /databases/{databaseId}/operations/{name}/import-bulk. Bulk-import records via a database operation */
+    "importBulk"(args: {
+      "databaseId": string | number;
+      "name": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.list` — GET /databases. List databases */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `databases.listGroupPermissions` — GET /databases/{databaseId}/group-permissions. List a database's group permissions */
+    "listGroupPermissions"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.listOperations` — GET /databases/{databaseId}/operations. List operations runnable on a database */
+    "listOperations"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.listPermissions` — GET /databases/{databaseId}/permissions. List a database's user permissions */
+    "listPermissions"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    "records": {
+      /** `databases.records.addToSet` — POST /databases/{databaseId}/records/stringset/add. Database records: stringset/add (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "addToSet"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.aggregate` — POST /databases/{databaseId}/records/aggregate. Database records: aggregate (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "aggregate"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.batch` — POST /databases/{databaseId}/records/batch. Database records: batch (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "batch"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.count` — POST /databases/{databaseId}/records/count. Database records: count (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "count"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.delete` — POST /databases/{databaseId}/records/delete. Database records: delete (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "delete"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.describe` — GET /databases/{databaseId}/records/describe. Database records: describe (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "describe"(args: {
+        "databaseId": string | number;
+        "modelName"?: string | number | boolean;
+      }): Promise<any>;
+      /** `databases.records.dropIndex` — POST /databases/{databaseId}/records/index/drop. Database records: index/drop (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "dropIndex"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.dropUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/drop. Database records: unique-constraint/drop (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "dropUniqueConstraint"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.increment` — POST /databases/{databaseId}/records/increment. Database records: increment (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "increment"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.listIndexes` — GET /databases/{databaseId}/records/indexes. Database records: indexes (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "listIndexes"(args: {
+        "databaseId": string | number;
+        "modelName"?: string | number | boolean;
+      }): Promise<any>;
+      /** `databases.records.listUniqueConstraints` — GET /databases/{databaseId}/records/unique-constraints. Database records: unique-constraints (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "listUniqueConstraints"(args: {
+        "databaseId": string | number;
+        "modelName"?: string | number | boolean;
+      }): Promise<any>;
+      /** `databases.records.models` — GET /databases/{databaseId}/records/models. Database records: models (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "models"(args: {
+        "databaseId": string | number;
+        "modelName"?: string | number | boolean;
+      }): Promise<any>;
+      /** `databases.records.patch` — POST /databases/{databaseId}/records/patch. Database records: patch (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "patch"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.query` — POST /databases/{databaseId}/records/query. Database records: query (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "query"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.registerIndex` — POST /databases/{databaseId}/records/index/register. Database records: index/register (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "registerIndex"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.registerUniqueConstraint` — POST /databases/{databaseId}/records/unique-constraint/register. Database records: unique-constraint/register (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "registerUniqueConstraint"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.removeFromSet` — POST /databases/{databaseId}/records/stringset/remove. Database records: stringset/remove (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "removeFromSet"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.save` — POST /databases/{databaseId}/records/save. Database records: save (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "save"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `databases.records.syncIndexes` — POST /databases/{databaseId}/records/indexes/sync. Database records: indexes/sync (requires manager-or-higher on the database, or an app-admin/owner role) */
+      "syncIndexes"(args: {
+        "databaseId": string | number;
+        body: unknown;
+      }): Promise<any>;
+    };
+    /** `databases.reindex` — POST /databases/{databaseId}/reindex. Reindex a database */
+    "reindex"(args: {
+      "databaseId": string | number;
+    }): Promise<any>;
+    /** `databases.revokeGroupPermission` — DELETE /databases/{databaseId}/group-permissions/{groupType}/{groupId}. Revoke a group permission on a database */
+    "revokeGroupPermission"(args: {
+      "databaseId": string | number;
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `databases.revokePermission` — DELETE /databases/{databaseId}/permissions/{userId}. Remove a user's database permission */
+    "revokePermission"(args: {
+      "databaseId": string | number;
+      "userId": string | number;
+    }): Promise<any>;
+    /** `databases.transferOwnership` — POST /databases/{databaseId}/permissions/transfer. Transfer database ownership */
+    "transferOwnership"(args: {
+      "databaseId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.update` — PATCH /databases/{databaseId}. Update a database */
+    "update"(args: {
+      "databaseId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `databases.updateMetadata` — PATCH /databases/{databaseId}/metadata. Update database metadata */
+    "updateMetadata"(args: {
+      "databaseId": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
+  "documents": {
+    /** `documents.addTag` — POST /documents/{documentId}/tags. Add a tag to a document */
+    "addTag"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    "aliases": {
+      /** `documents.aliases.delete` — DELETE /document-aliases/{scope}/{aliasKey}. Delete a (scope, aliasKey) document alias binding */
+      "delete"(args: {
+        "scope": string | number;
+        "aliasKey": string | number;
+      }): Promise<any>;
+      /** `documents.aliases.listForDocument` — GET /documents/{documentId}/aliases. List aliases bound to a document */
+      "listForDocument"(args: {
+        "documentId": string | number;
+      }): Promise<any>;
+      /** `documents.aliases.resolve` — GET /document-aliases/{scope}/{aliasKey}. Resolve the document bound to a (scope, aliasKey) alias */
+      "resolve"(args: {
+        "scope": string | number;
+        "aliasKey": string | number;
+      }): Promise<any>;
+      /** `documents.aliases.set` — PUT /document-aliases/{scope}/{aliasKey}. Bind a (scope, aliasKey) alias to a document */
+      "set"(args: {
+        "scope": string | number;
+        "aliasKey": string | number;
+        body: unknown;
+      }): Promise<any>;
+    };
+    /** `documents.approveAccessRequest` — POST /documents/{documentId}/access-requests/{requestId}/approve. Approve a document access request */
+    "approveAccessRequest"(args: {
+      "documentId": string | number;
+      "requestId": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    "blobs": {
+      /** `documents.blobs.delete` — DELETE /documents/{documentId}/blobs/{blobId}. Delete a document blob */
+      "delete"(args: {
+        "documentId": string | number;
+        "blobId": string | number;
+      }): Promise<any>;
+      /** `documents.blobs.downloadHeaders` — HEAD /documents/{documentId}/blobs/{blobId}/download. Get document blob download headers (ETag/304 support) */
+      "downloadHeaders"(args: {
+        "documentId": string | number;
+        "blobId": string | number;
+      }): Promise<HeaderResult>;
+      /** `documents.blobs.downloadUrl` — GET /documents/{documentId}/blobs/{blobId}/download. Download a document blob's bytes */
+      "downloadUrl"(args: {
+        "documentId": string | number;
+        "blobId": string | number;
+        "disposition"?: string | number | boolean;
+      }): Promise<Uint8Array>;
+      /** `documents.blobs.get` — GET /documents/{documentId}/blobs/{blobId}. Get a document blob's metadata */
+      "get"(args: {
+        "documentId": string | number;
+        "blobId": string | number;
+      }): Promise<any>;
+      /** `documents.blobs.list` — GET /documents/{documentId}/blobs. List blobs attached to a document */
+      "list"(args: {
+        "documentId": string | number;
+      }): Promise<any>;
+      /** `documents.blobs.upload` — PUT /documents/{documentId}/blobs/{blobId}. Upload a document blob with a client-specified id (immutable + idempotent) */
+      "upload"(args: {
+        "documentId": string | number;
+        "blobId": string | number;
+        "X-Blob-Filename": string | number;
+        "X-Blob-Size": string | number;
+        "X-Blob-Sha256": string | number;
+        body: ArrayBuffer | Uint8Array | string;
+      }): Promise<any>;
+      /** `documents.blobs.uploadWithoutId` — PUT /documents/{documentId}/blobs. Deprecated: upload a document blob without a client-specified id */
+      "uploadWithoutId"(args: {
+        "documentId": string | number;
+      }): Promise<any>;
+    };
+    /** `documents.clearLinkAccess` — DELETE /documents/{documentId}/link-access. Turn off the document's link access */
+    "clearLinkAccess"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.create` — POST /documents. Create a new document */
+    "create"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.createInvitation` — POST /documents/{documentId}/invitations. Send an invitation to collaborate on a document */
+    "createInvitation"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.createWithAlias` — POST /documents/create-with-alias. Create a document and bind it to an alias */
+    "createWithAlias"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.debugDumpUpdates` — POST /documents/{documentId}/debug/dump-updates. Dump a document's raw CRDT update log (debug) */
+    "debugDumpUpdates"(args: {
+      "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "offset"?: string | number | boolean;
+      "includeData"?: string | number | boolean;
+      "includeR2Data"?: string | number | boolean;
+      body?: unknown;
+    }): Promise<any>;
+    /** `documents.debugMerge` — POST /documents/{documentId}/debug/merge. Force-merge a document's pending updates (debug) */
+    "debugMerge"(args: {
+      "documentId": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    /** `documents.debugMergeBlock` — POST /documents/{documentId}/debug/merge-block. Merge a specific update block of a document (debug) */
+    "debugMergeBlock"(args: {
+      "documentId": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    /** `documents.debugRestore` — POST /documents/debug/restore. Restore a document from a prior state snapshot (debug) */
+    "debugRestore"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.debugStats` — GET /documents/{documentId}/debug/stats. Get document storage/update stats (debug) */
+    "debugStats"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.declineInvitation` — POST /documents/{documentId}/invitations/{invitationId}/decline. Decline a document invitation (invitee only) */
+    "declineInvitation"(args: {
+      "documentId": string | number;
+      "invitationId": string | number;
+    }): Promise<any>;
+    /** `documents.delete` — DELETE /documents/{documentId}. Delete a document */
+    "delete"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.deleteInvitation` — DELETE /documents/{documentId}/invitations/{invitationId}. Cancel a pending document invitation */
+    "deleteInvitation"(args: {
+      "documentId": string | number;
+      "invitationId": string | number;
+    }): Promise<any>;
+    /** `documents.denyAccessRequest` — POST /documents/{documentId}/access-requests/{requestId}/deny. Deny a document access request */
+    "denyAccessRequest"(args: {
+      "documentId": string | number;
+      "requestId": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    /** `documents.exportChain` — GET /documents/{documentId}/export/chain. Export chain of a large document (snapshot + sealed overlays + open epoch) */
+    "exportChain"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.exportState` — GET /documents/{documentId}/export/state. Export a document's encoded CRDT state */
+    "exportState"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.get` — GET /documents/{documentId}. Get a single document by id */
+    "get"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.getImportChainStatus` — GET /documents/{documentId}/import/chain. How far a large document's chain import has got */
+    "getImportChainStatus"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.getLinkAccess` — GET /documents/{documentId}/link-access. Get the document's "anyone with the link" access level */
+    "getLinkAccess"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.getOrCreateWithAlias` — POST /documents/get-or-create-with-alias. Get the document bound to an alias, creating it if absent (idempotent) */
+    "getOrCreateWithAlias"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.getPermissions` — GET /documents/{documentId}/permissions. List a document's user permissions */
+    "getPermissions"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.getSchema` — GET /documents/{documentId}/schema. Introspect a document's model schema */
+    "getSchema"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.getStats` — GET /documents/{documentId}/stats. Document statistics (record/model/blob counts, approximate size) */
+    "getStats"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.grantGroupPermission` — POST /documents/{documentId}/group-permissions. Grant a group permission on a document */
+    "grantGroupPermission"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.importChain` — POST /documents/{documentId}/import/chain. Install an uploaded chain into a large document */
+    "importChain"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.importChainArtifact` — POST /documents/{documentId}/import/chain/artifact. Upload one artifact of a large document's import chain */
+    "importChainArtifact"(args: {
+      "documentId": string | number;
+      "kind"?: string | number | boolean;
+      "epoch"?: string | number | boolean;
+      "buildId"?: string | number | boolean;
+      "model"?: string | number | boolean;
+      "index"?: string | number | boolean;
+      body: ArrayBuffer | Uint8Array | string;
+    }): Promise<any>;
+    /** `documents.importState` — POST /documents/{documentId}/import/state. Import encoded CRDT state into a document */
+    "importState"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.list` — GET /documents. List documents the caller can access */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `documents.listAccessRequests` — GET /documents/{documentId}/access-requests. List access requests for a document */
+    "listAccessRequests"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.listGroupPermissions` — GET /documents/{documentId}/group-permissions. List a document's group permissions */
+    "listGroupPermissions"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.listInvitations` — GET /documents/{documentId}/invitations. List invitations issued for a document */
+    "listInvitations"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.listPendingInvitations` — GET /documents/{documentId}/pending-invitations. List a document's pending (deferred) invitations */
+    "listPendingInvitations"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `documents.open` — POST /documents/open. Open a document for collaboration (resolves access + alias) */
+    "open"(args: {
+      body: unknown;
+    }): Promise<any>;
+    "records": {
+      /** `documents.records.aggregate` — POST /documents/{documentId}/records/{model}/aggregate. Aggregate records in a document model (count/sum/avg/min/max, optional grouping) */
+      "aggregate"(args: {
+        "documentId": string | number;
+        "model": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `documents.records.bulk` — POST /documents/{documentId}/records/bulk. Apply an atomic multi-model record blob to a document (create/patch/delete) */
+      "bulk"(args: {
+        "documentId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `documents.records.count` — GET /documents/{documentId}/records/{model}/count. Count records in a document model */
+      "count"(args: {
+        "documentId": string | number;
+        "model": string | number;
+      }): Promise<any>;
+      /** `documents.records.delete` — DELETE /documents/{documentId}/records/{model}/{recordId}. Delete a record from a document model */
+      "delete"(args: {
+        "documentId": string | number;
+        "model": string | number;
+        "recordId": string | number;
+      }): Promise<any>;
+      /** `documents.records.patch` — PATCH /documents/{documentId}/records/{model}/{recordId}. Merge fields into an existing record in a document model */
+      "patch"(args: {
+        "documentId": string | number;
+        "model": string | number;
+        "recordId": string | number;
+        body: unknown;
+      }): Promise<any>;
+      /** `documents.records.query` — GET /documents/{documentId}/records/{model}. Query records in a document model */
+      "query"(args: {
+        "documentId": string | number;
+        "model": string | number;
+      }): Promise<any>;
+      /** `documents.records.save` — POST /documents/{documentId}/records/{model}. Create or replace a record in a document model */
+      "save"(args: {
+        "documentId": string | number;
+        "model": string | number;
+        body: unknown;
+      }): Promise<any>;
+    };
+    /** `documents.removePermissionByEmail` — DELETE /documents/{documentId}/permissions. Revoke a user's permission on a document by email (?email=) */
+    "removePermissionByEmail"(args: {
+      "documentId": string | number;
+      "email"?: string | number | boolean;
+    }): Promise<any>;
+    /** `documents.removePermissionByUserId` — DELETE /documents/{documentId}/permissions/{userId}. Revoke a user's permission on a document by user id */
+    "removePermissionByUserId"(args: {
+      "documentId": string | number;
+      "userId": string | number;
+    }): Promise<any>;
+    /** `documents.removeTag` — DELETE /documents/{documentId}/tags/{tag}. Remove a tag from a document */
+    "removeTag"(args: {
+      "documentId": string | number;
+      "tag": string | number;
+    }): Promise<any>;
+    /** `documents.requestAccess` — POST /documents/{documentId}/access-requests. Request access to a document */
+    "requestAccess"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.revokeGroupPermission` — DELETE /documents/{documentId}/group-permissions/{groupType}/{groupId}. Revoke a group permission on a document */
+    "revokeGroupPermission"(args: {
+      "documentId": string | number;
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `documents.setLinkAccess` — PUT /documents/{documentId}/link-access. Set the document's "anyone with the link" access level */
+    "setLinkAccess"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.transferOwnership` — POST /documents/{documentId}/permissions/transfer. Transfer ownership of a document to another user */
+    "transferOwnership"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.update` — PUT /documents/{documentId}. Update a document's metadata */
+    "update"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.updatePermissions` — PUT /documents/{documentId}/permissions. Grant or update a user's permission on a document */
+    "updatePermissions"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Validate access to a document (accepts/upgrades pending invitations) */
+    "validateAccess"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+  };
+  "functions": {
+    /** `functions.invoke` — POST /functions/{functionKey}. Invoke a server function synchronously and return its result */
+    "invoke"(args: {
+      "functionKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
+  };
+}
+
+export interface FunctionContext {
+  user: FunctionUser;
+  trigger: FunctionTrigger;
+  api: FunctionApi;
+}
+
+export declare const SDK_STUB_VERSION: string;
+
+/**
+ * Declare a server function's handler.
+ *
+ * Both authoring styles reach the platform bootstrap identically — a plain
+ * default export taking `(input, ctx)` runs exactly as a wrapped one does —
+ * so this is a typing and intent marker, not a different calling convention.
+ */
+export declare function defineFunction<TInput = unknown, TOutput = unknown>(
+  handler: (input: TInput, ctx: FunctionContext) => TOutput | Promise<TOutput>
+): (input: TInput, ctx: FunctionContext) => Promise<TOutput>;
+
+declare const _default: {
+  SDK_STUB_VERSION: string;
+  defineFunction: typeof defineFunction;
+};
+export default _default;

package/index.js

@@ -0,0 +1,34 @@
+/**
+ * `primitive-functions` — the module a Primitive server function imports (#3179).
+ *
+ * A function's bundle is built by `primitive config push` with esbuild, which
+ * inlines every npm dependency EXCEPT this one: the platform loader supplies it
+ * at invoke time, so a function always runs against the SDK the platform is
+ * running, not the copy that happened to be installed when the code was last
+ * pushed.
+ *
+ * That makes this package a name reservation with a working shape rather than
+ * an implementation. The runtime surface — the typed API client, the durable
+ * primitives, the trigger helpers — belongs to #3180 and the children after it.
+ * Everything here throws if it is ever reached, because reaching it means the
+ * loader did not substitute the platform copy, and a silent no-op there would
+ * be a function that appears to run and does nothing.
+ */
+
+const NOT_PROVIDED =
+  "primitive-functions is supplied by the Primitive platform at invoke time. " +
+  "Reaching this stub means the function is running outside a Primitive " +
+  "sandbox, or the loader did not substitute the platform copy.";
+
+/** The version of the reservation stub, so a mis-substitution is diagnosable. */
+export const SDK_STUB_VERSION = "0.0.1";
+
+/**
+ * Declare a function's handler. The platform copy returns the handler wrapped
+ * with its invocation context; this one refuses, loudly.
+ */
+export function defineFunction() {
+  throw new Error(NOT_PROVIDED);
+}
+
+export default { SDK_STUB_VERSION, defineFunction };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "primitive-functions",
+  "version": "0.1.0-alpha.0",
+  "description": "The module a Primitive server function imports. Supplied by the platform at invoke time; reserved here so the name is ours before the runtime lands.",
+  "license": "UNLICENSED",
+  "author": "Primitive LLC",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}