@starkeep/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Koller, Pedro Pinto, Craig Schroeder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @starkeep/sdk
+
+High-level facade over all Starkeep packages. Provides a single entry point for data operations, metadata generation, search, aggregations, sync, access control, and API handling.
+
+## Installation
+
+```bash
+pnpm add @starkeep/sdk
+```
+
+## Usage
+
+```ts
+import { createStarkeepSdk } from "@starkeep/sdk";
+
+const starkeepSdk = createStarkeepSdk({
+  databaseAdapter: localDatabaseAdapter,
+  objectStorageAdapter: localObjectStorage,
+  ownerId: "user-123",
+  nodeId: "device-abc",
+  // Optional: enable sync by providing remote adapters
+  remoteDatabaseAdapter: remoteDatabaseAdapter,
+  remoteObjectStorageAdapter: remoteObjectStorage,
+  // Optional: register metadata generators
+  generators: [imageDimensionsGenerator, textPreviewGenerator],
+});
+
+// Data operations
+const record = await starkeepSdk.data.put({
+  type: "photo",
+  ownerId: "user-123",
+  payload: { title: "Sunset", tags: ["nature"] },
+});
+
+const recordWithFile = await starkeepSdk.data.putWithFile(
+  { type: "photo", ownerId: "user-123", payload: { title: "Beach" } },
+  fileBuffer,
+  "image/jpeg",
+);
+
+const fetched = await starkeepSdk.data.get(record.id);
+await starkeepSdk.data.delete(record.id);
+
+// Metadata
+const generationResults = await starkeepSdk.metadata.generateAll(record.id, "photo");
+const metadataRecords = await starkeepSdk.metadata.getForRecord(record.id);
+
+// Search
+const searchResult = await starkeepSdk.index.search({
+  types: ["photo"],
+  fullTextSearch: "sunset",
+  limit: 20,
+});
+
+// Aggregations
+const aggregationResult = await starkeepSdk.aggregations.compute({
+  dateGranularity: "month",
+});
+
+// Sync (available when remote adapters are provided)
+if (starkeepSdk.sync) {
+  const syncResult = await starkeepSdk.sync.fullSync();
+  const unsubscribe = starkeepSdk.sync.onUpdate((changeEvent) => {
+    console.log(changeEvent.eventType, changeEvent.recordIds);
+  });
+}
+
+// Access control
+const policy = await starkeepSdk.accessControl.createPolicy({
+  subjectType: "user",
+  subjectId: "user-456",
+  resourceType: "type",
+  resourceId: "photo",
+  permissions: ["read"],
+});
+
+// API
+const apiResponse = await starkeepSdk.api.handleRequest({
+  path: "/photos/v1/albums",
+  method: "GET",
+  subject: { subjectType: "user", subjectId: "user-456" },
+});
+
+// Cleanup
+await starkeepSdk.close();
+```
+
+## API
+
+### Factory Function
+
+| Function | Description |
+|---|---|
+| `createStarkeepSdk(options)` | Creates a `StarkeepSdk` instance wiring together all subsystems |
+
+### `StarkeepSdk`
+
+| Member | Description |
+|---|---|
+| `data` | `DataOperations` -- put, get, delete records and files |
+| `metadata` | `MetadataOperations` -- generate and retrieve metadata for records |
+| `index` | `IndexOperations` -- search across data and metadata |
+| `aggregations` | `AggregationOperations` -- compute counts, sizes, and histograms |
+| `sync` | `SyncOperations \| null` -- push, pull, full sync, and change subscriptions (null when no remote adapters) |
+| `accessControl` | `AccessControlOperations` -- create/revoke policies and check access |
+| `api` | `ApiOperations` -- handle shared space API requests |
+| `close()` | Clean up resources |
+
+### `StarkeepSdkOptions`
+
+| Option | Required | Description |
+|---|---|---|
+| `databaseAdapter` | Yes | Local database adapter |
+| `objectStorageAdapter` | Yes | Local object storage adapter |
+| `ownerId` | Yes | Owner identifier for records |
+| `nodeId` | Yes | Unique node ID for HLC clock |
+| `clock` | No | Custom HLC clock instance |
+| `remoteDatabaseAdapter` | No | Remote database adapter (enables sync) |
+| `remoteObjectStorageAdapter` | No | Remote object storage adapter (enables sync) |
+| `generators` | No | Metadata generator definitions to register |
+
+### Re-exported Types
+
+The SDK re-exports commonly used types from `@starkeep/protocol-primitives` for convenience: `StarkeepId`, `DataRecord`, `MetadataRecord`, `HLCTimestamp`, `CreateDataRecordInput`, `CreateMetadataRecordInput`.
+
+## Testing
+
+```bash
+pnpm --filter @starkeep/sdk test
+```

package/dist/index.cjs

@@ -0,0 +1,290 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createStarkeepSdk: () => createStarkeepSdk
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sdk.ts
+var import_protocol_primitives = require("@starkeep/protocol-primitives");
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_query_orchestrator = require("@starkeep/query-orchestrator");
+var import_sync_engine = require("@starkeep/sync-engine");
+var import_access_control = require("@starkeep/access-control");
+var import_shared_space_api = require("@starkeep/shared-space-api");
+async function sha256Hex(data) {
+  const copy = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+  const buf = await crypto.subtle.digest("SHA-256", copy);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function metadataCategory(typeOrCategory) {
+  return (0, import_protocol_primitives.isCategoryId)(typeOrCategory) ? typeOrCategory : (0, import_protocol_primitives.categoryOf)(typeOrCategory);
+}
+async function createStarkeepSdk(options) {
+  const {
+    databaseAdapter: rawDatabaseAdapter,
+    objectStorageAdapter,
+    accessPolicyStore,
+    sharingTokenStore,
+    ownerId,
+    nodeId,
+    syncStateStore,
+    subject
+  } = options;
+  await rawDatabaseAdapter.init();
+  await objectStorageAdapter.init();
+  const initialHlcState = await syncStateStore?.getHlcClockState() ?? void 0;
+  let pendingClockState = null;
+  let clockFlushTimer = null;
+  const clock = options.clock ?? (0, import_protocol_primitives.createHLCClock)({
+    nodeId,
+    wallClockFunction: Date.now,
+    initialState: initialHlcState,
+    onTick: syncStateStore ? (state) => {
+      pendingClockState = state;
+      if (clockFlushTimer) return;
+      clockFlushTimer = setTimeout(() => {
+        clockFlushTimer = null;
+        if (pendingClockState) {
+          void syncStateStore.setHlcClockState(pendingClockState);
+        }
+      }, 5e3);
+    } : void 0
+  });
+  const changeNotifier = options.changeNotifier ?? (0, import_sync_engine.createChangeNotifier)();
+  const accessControlEngine = (0, import_access_control.createAccessControlEngine)({
+    policyStore: accessPolicyStore,
+    tokenStore: sharingTokenStore,
+    clock,
+    ownerId
+  });
+  await accessControlEngine.loadPolicies();
+  const databaseAdapter = subject ? (0, import_access_control.createEnforcedDatabaseAdapter)({
+    databaseAdapter: rawDatabaseAdapter,
+    accessControlEngine,
+    subjectType: subject.subjectType,
+    subjectId: subject.subjectId
+  }) : rawDatabaseAdapter;
+  const unifiedIndex = (0, import_query_orchestrator.createUnifiedIndex)({ databaseAdapter });
+  function logChange(record) {
+    changeNotifier.emit({
+      eventType: "local-change-recorded",
+      recordIds: [record.id],
+      timestamp: clock.now()
+    });
+  }
+  const sharedSpaceApi = (0, import_shared_space_api.createSharedSpaceApi)({
+    databaseAdapter,
+    objectStorageAdapter,
+    clock,
+    ownerId,
+    changeNotifier,
+    getAppSpecific: options.getAppSpecific
+  });
+  async function writeRecordAndMetadata(input, fileBytes, contentType, originalFilename) {
+    const contentHash = await sha256Hex(fileBytes);
+    const objectStorageKey = (0, import_protocol_primitives.dataRecordObjectKey)(input.type, contentHash);
+    const record = (0, import_protocol_primitives.createDataRecord)(
+      {
+        ...input,
+        contentHash,
+        objectStorageKey,
+        mimeType: contentType,
+        sizeBytes: fileBytes.length,
+        originalFilename
+      },
+      clock
+    );
+    await databaseAdapter.put(record);
+    if (input.metadata && metadataCategory(input.type) !== "other") {
+      await databaseAdapter.putMetadata(input.type, {
+        ...input.metadata,
+        recordId: record.id
+      });
+    }
+    logChange(record);
+    return record;
+  }
+  return {
+    data: {
+      async putWithFile(input, file, contentType) {
+        const contentHash = await sha256Hex(file);
+        const objectStorageKey = (0, import_protocol_primitives.dataRecordObjectKey)(input.type, contentHash);
+        await objectStorageAdapter.put(objectStorageKey, file, { contentType });
+        return writeRecordAndMetadata(
+          { ...input, contentHash, objectStorageKey },
+          file,
+          contentType,
+          input.originalFilename ?? null
+        );
+      },
+      async putWithLocalFile(input, filePath, contentType) {
+        const fileBytes = await (0, import_promises.readFile)(filePath);
+        const contentHash = await sha256Hex(fileBytes);
+        const objectStorageKey = (0, import_protocol_primitives.dataRecordObjectKey)(input.type, contentHash);
+        if (objectStorageAdapter.putSymlink) {
+          await objectStorageAdapter.putSymlink(objectStorageKey, filePath, { contentType });
+        } else {
+          await objectStorageAdapter.put(objectStorageKey, fileBytes, { contentType });
+        }
+        return writeRecordAndMetadata(
+          input,
+          fileBytes,
+          contentType,
+          input.originalFilename ?? (0, import_node_path.basename)(filePath)
+        );
+      },
+      async putWithExistingBlob(input, blob) {
+        const record = (0, import_protocol_primitives.createDataRecord)(
+          {
+            ...input,
+            contentHash: blob.contentHash,
+            objectStorageKey: blob.objectStorageKey,
+            mimeType: blob.mimeType,
+            sizeBytes: blob.sizeBytes,
+            originalFilename: input.originalFilename ?? null
+          },
+          clock
+        );
+        await databaseAdapter.put(record);
+        if (input.metadata) {
+          await databaseAdapter.putMetadata(input.type, {
+            ...input.metadata,
+            recordId: record.id
+          });
+        }
+        logChange(record);
+        return record;
+      },
+      async get(recordId) {
+        const record = await databaseAdapter.get(recordId);
+        if (!record) return null;
+        if (record.deletedAt) return null;
+        return record;
+      },
+      async update(recordId, patch) {
+        const existing = await databaseAdapter.get(recordId);
+        if (!existing) {
+          throw new Error(`No data record found with id ${recordId}`);
+        }
+        const updated = {
+          ...existing,
+          originalFilename: patch.originalFilename ?? existing.originalFilename,
+          parentId: patch.parentId ?? existing.parentId,
+          version: existing.version + 1,
+          updatedAt: clock.now()
+        };
+        await databaseAdapter.put(updated);
+        logChange(updated);
+        return updated;
+      },
+      async delete(recordId) {
+        const existing = await databaseAdapter.get(recordId);
+        if (!existing) return;
+        const ts = clock.now();
+        await databaseAdapter.delete(recordId, ts);
+        await databaseAdapter.deleteMetadata(existing.type, recordId);
+        const tombstone = {
+          ...existing,
+          updatedAt: ts,
+          deletedAt: ts,
+          version: existing.version + 1
+        };
+        logChange(tombstone);
+      },
+      async query(params) {
+        const result = await databaseAdapter.query(params);
+        return result.records;
+      },
+      // `typeId` may be a record's extension or a category id; the adapter
+      // derives the per-category metadata table. The `other` category has no
+      // metadata table, so these are no-ops for it.
+      async putMetadata(typeId, row) {
+        if (metadataCategory(typeId) === "other") return;
+        await databaseAdapter.putMetadata(typeId, row);
+      },
+      async getMetadata(typeId, recordId) {
+        if (metadataCategory(typeId) === "other") return null;
+        return databaseAdapter.getMetadata(typeId, recordId);
+      },
+      async getMetadataByIds(typeId, recordIds) {
+        if (metadataCategory(typeId) === "other") return /* @__PURE__ */ new Map();
+        return databaseAdapter.getMetadataByIds(typeId, recordIds);
+      }
+    },
+    index: {
+      async search(query) {
+        return unifiedIndex.search(query);
+      }
+    },
+    accessControl: {
+      async createPolicy(input) {
+        if (subject) {
+          throw new Error(
+            "createPolicy is not available on an app-scoped SDK. Policies are managed by the admin layer."
+          );
+        }
+        return accessControlEngine.createPolicy(input);
+      },
+      async revokePolicy(policyId) {
+        if (subject) {
+          throw new Error(
+            "revokePolicy is not available on an app-scoped SDK. Policies are managed by the admin layer."
+          );
+        }
+        return accessControlEngine.revokePolicy(policyId);
+      },
+      async listPolicies(listOptions) {
+        return accessControlEngine.listPolicies(listOptions);
+      },
+      async checkAccess(request) {
+        return accessControlEngine.checkAccess(request);
+      }
+    },
+    api: {
+      get router() {
+        return sharedSpaceApi.router;
+      },
+      async handleRequest(request) {
+        return sharedSpaceApi.handleRequest(request);
+      },
+      handleWebSocketConnect(connection) {
+        return sharedSpaceApi.handleWebSocketConnect(connection);
+      }
+    },
+    changeNotifier,
+    clock,
+    async close() {
+      if (clockFlushTimer) {
+        clearTimeout(clockFlushTimer);
+        clockFlushTimer = null;
+      }
+      if (pendingClockState && syncStateStore) {
+        await syncStateStore.setHlcClockState(pendingClockState);
+      }
+      await databaseAdapter.close();
+      await objectStorageAdapter.close();
+    }
+  };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sdk.ts"],"sourcesContent":["export type {\n  StarkeepSdk,\n  StarkeepSdkOptions,\n  DataOperations,\n  IndexOperations,\n  AccessControlOperations,\n  ApiOperations,\n} from \"./types.js\";\n\nexport { createStarkeepSdk } from \"./sdk.js\";\n\n// Re-export commonly used types from core for convenience\nexport type {\n  StarkeepId,\n  DataRecord,\n  HLCTimestamp,\n  CreateDataRecordInput,\n} from \"@starkeep/protocol-primitives\";\n","import {\n  createHLCClock,\n  createDataRecord,\n  dataRecordObjectKey,\n  categoryOf,\n  isCategoryId,\n  type DataRecord,\n  type MetadataRow,\n} from \"@starkeep/protocol-primitives\";\nimport { readFile } from \"node:fs/promises\";\nimport { basename } from \"node:path\";\nasync function sha256Hex(data: Uint8Array | Buffer): Promise<string> {\n  const copy = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;\n  const buf = await crypto.subtle.digest(\"SHA-256\", copy);\n  return Array.from(new Uint8Array(buf))\n    .map((b) => b.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n}\nimport { createUnifiedIndex } from \"@starkeep/query-orchestrator\";\nimport { createChangeNotifier } from \"@starkeep/sync-engine\";\nimport { createAccessControlEngine, createEnforcedDatabaseAdapter } from \"@starkeep/access-control\";\nimport { createSharedSpaceApi } from \"@starkeep/shared-space-api\";\nimport type {\n  StarkeepSdk,\n  StarkeepSdkOptions,\n  DataPutInput,\n} from \"./types.js\";\n\n// Resolve a record's type/extension (or a category id) to its metadata\n// category. `other` has no metadata table, so callers skip persistence for it.\nfunction metadataCategory(typeOrCategory: string): string {\n  return isCategoryId(typeOrCategory) ? typeOrCategory : categoryOf(typeOrCategory);\n}\n\nexport async function createStarkeepSdk(\n  options: StarkeepSdkOptions,\n): Promise<StarkeepSdk> {\n  const {\n    databaseAdapter: rawDatabaseAdapter,\n    objectStorageAdapter,\n    accessPolicyStore,\n    sharingTokenStore,\n    ownerId,\n    nodeId,\n    syncStateStore,\n    subject,\n  } = options;\n\n  await rawDatabaseAdapter.init();\n  await objectStorageAdapter.init();\n\n  // Seed the clock from persisted state and debounce write-back on tick,\n  // so a restart resumes with an HLC causally after anything we emitted.\n  // The clock state is global (one clock per node) — the supervisor's\n  // per-app cursors live alongside it in the same store but are owned\n  // elsewhere.\n  const initialHlcState =\n    (await syncStateStore?.getHlcClockState()) ?? undefined;\n  let pendingClockState: { wallTime: number; counter: number } | null = null;\n  let clockFlushTimer: NodeJS.Timeout | null = null;\n  const clock =\n    options.clock ??\n    createHLCClock({\n      nodeId,\n      wallClockFunction: Date.now,\n      initialState: initialHlcState,\n      onTick: syncStateStore\n        ? (state) => {\n            pendingClockState = state;\n            if (clockFlushTimer) return;\n            clockFlushTimer = setTimeout(() => {\n              clockFlushTimer = null;\n              if (pendingClockState) {\n                void syncStateStore.setHlcClockState(pendingClockState);\n              }\n            }, 5000);\n          }\n        : undefined,\n    });\n\n  // One shared change notifier. Writes emit `local-change-recorded`; the\n  // supervisor's per-app sync engines forward their own pull/conflict events\n  // onto this same notifier so consumers (sharedSpaceApi, SSE clients) see\n  // one unified stream. Callers may inject a notifier (e.g. the local-data-\n  // server hoists it to share with the app-specific factory, which emits\n  // its own local-change events tagged with the writing app's id).\n  const changeNotifier = options.changeNotifier ?? createChangeNotifier();\n\n  // When a subject is provided, wrap the adapter so every operation is\n  // gated by access control and the private-storage structural rule.\n  const accessControlEngine = createAccessControlEngine({\n    policyStore: accessPolicyStore,\n    tokenStore: sharingTokenStore,\n    clock,\n    ownerId,\n  });\n  await accessControlEngine.loadPolicies();\n\n  const databaseAdapter = subject\n    ? createEnforcedDatabaseAdapter({\n        databaseAdapter: rawDatabaseAdapter,\n        accessControlEngine,\n        subjectType: subject.subjectType,\n        subjectId: subject.subjectId,\n      })\n    : rawDatabaseAdapter;\n\n  const unifiedIndex = createUnifiedIndex({ databaseAdapter });\n\n  /**\n   * Emit a `local-change-recorded` event for a write. The supervisor wakes its\n   * exchange loop in response; the records-table row itself is the durable\n   * source of truth for what to ship (no separate change log).\n   */\n  function logChange(record: DataRecord): void {\n    changeNotifier.emit({\n      eventType: \"local-change-recorded\",\n      recordIds: [record.id],\n      timestamp: clock.now(),\n    });\n  }\n\n  const sharedSpaceApi = createSharedSpaceApi({\n    databaseAdapter,\n    objectStorageAdapter,\n    clock,\n    ownerId,\n    changeNotifier,\n    getAppSpecific: options.getAppSpecific,\n  });\n\n  async function writeRecordAndMetadata(\n    input: DataPutInput,\n    fileBytes: Uint8Array,\n    contentType: string,\n    originalFilename: string | null,\n  ): Promise<DataRecord> {\n    const contentHash = await sha256Hex(fileBytes);\n    const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n    const record = createDataRecord(\n      {\n        ...input,\n        contentHash,\n        objectStorageKey,\n        mimeType: contentType,\n        sizeBytes: fileBytes.length,\n        originalFilename,\n      },\n      clock,\n    );\n    await databaseAdapter.put(record);\n    if (input.metadata && metadataCategory(input.type) !== \"other\") {\n      await databaseAdapter.putMetadata(input.type, {\n        ...input.metadata,\n        recordId: record.id,\n      });\n    }\n    logChange(record);\n    return record;\n  }\n\n  return {\n    data: {\n      async putWithFile(input, file, contentType) {\n        const contentHash = await sha256Hex(file);\n        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n        await objectStorageAdapter.put(objectStorageKey, file, { contentType });\n        return writeRecordAndMetadata(\n          { ...input, contentHash, objectStorageKey } as DataPutInput,\n          file,\n          contentType,\n          input.originalFilename ?? null,\n        );\n      },\n\n      async putWithLocalFile(input, filePath, contentType) {\n        const fileBytes = await readFile(filePath);\n        const contentHash = await sha256Hex(fileBytes);\n        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n        if (objectStorageAdapter.putSymlink) {\n          await objectStorageAdapter.putSymlink(objectStorageKey, filePath, { contentType });\n        } else {\n          await objectStorageAdapter.put(objectStorageKey, fileBytes, { contentType });\n        }\n\n        return writeRecordAndMetadata(\n          input,\n          fileBytes,\n          contentType,\n          input.originalFilename ?? basename(filePath),\n        );\n      },\n\n      async putWithExistingBlob(input, blob) {\n        // Bytes are already in object storage (uploaded out-of-band, e.g. via\n        // a presigned PUT). Skip the upload + re-hash; trust the caller's\n        // contentHash and sizeBytes. The records-table row is otherwise\n        // identical to what putWithFile would produce.\n        const record = createDataRecord(\n          {\n            ...input,\n            contentHash: blob.contentHash,\n            objectStorageKey: blob.objectStorageKey,\n            mimeType: blob.mimeType,\n            sizeBytes: blob.sizeBytes,\n            originalFilename: input.originalFilename ?? null,\n          } as DataPutInput as never,\n          clock,\n        );\n        await databaseAdapter.put(record);\n        if (input.metadata) {\n          await databaseAdapter.putMetadata(input.type, {\n            ...input.metadata,\n            recordId: record.id,\n          });\n        }\n        logChange(record);\n        return record;\n      },\n\n      async get(recordId) {\n        const record = await databaseAdapter.get(recordId);\n        if (!record) return null;\n        if (record.deletedAt) return null;\n        return record;\n      },\n\n      async update(recordId, patch) {\n        const existing = await databaseAdapter.get(recordId);\n        if (!existing) {\n          throw new Error(`No data record found with id ${recordId}`);\n        }\n        const updated: DataRecord = {\n          ...existing,\n          originalFilename: patch.originalFilename ?? existing.originalFilename,\n          parentId: patch.parentId ?? existing.parentId,\n          version: existing.version + 1,\n          updatedAt: clock.now(),\n        };\n        await databaseAdapter.put(updated);\n        logChange(updated);\n        return updated;\n      },\n\n      async delete(recordId) {\n        const existing = await databaseAdapter.get(recordId);\n        if (!existing) return;\n        const ts = clock.now();\n        await databaseAdapter.delete(recordId, ts);\n        await databaseAdapter.deleteMetadata(existing.type, recordId);\n        const tombstone: DataRecord = {\n          ...existing,\n          updatedAt: ts,\n          deletedAt: ts,\n          version: existing.version + 1,\n        };\n        logChange(tombstone);\n      },\n\n      async query(params) {\n        const result = await databaseAdapter.query(params);\n        return result.records;\n      },\n\n      // `typeId` may be a record's extension or a category id; the adapter\n      // derives the per-category metadata table. The `other` category has no\n      // metadata table, so these are no-ops for it.\n      async putMetadata(typeId: string, row: MetadataRow) {\n        if (metadataCategory(typeId) === \"other\") return;\n        await databaseAdapter.putMetadata(typeId, row);\n      },\n\n      async getMetadata(typeId, recordId) {\n        if (metadataCategory(typeId) === \"other\") return null;\n        return databaseAdapter.getMetadata(typeId, recordId);\n      },\n\n      async getMetadataByIds(typeId, recordIds) {\n        if (metadataCategory(typeId) === \"other\") return new Map();\n        return databaseAdapter.getMetadataByIds(typeId, recordIds);\n      },\n    },\n\n    index: {\n      async search(query) {\n        return unifiedIndex.search(query);\n      },\n    },\n\n    accessControl: {\n      async createPolicy(input) {\n        if (subject) {\n          throw new Error(\n            \"createPolicy is not available on an app-scoped SDK. Policies are managed by the admin layer.\",\n          );\n        }\n        return accessControlEngine.createPolicy(input);\n      },\n\n      async revokePolicy(policyId) {\n        if (subject) {\n          throw new Error(\n            \"revokePolicy is not available on an app-scoped SDK. Policies are managed by the admin layer.\",\n          );\n        }\n        return accessControlEngine.revokePolicy(policyId);\n      },\n\n      async listPolicies(listOptions) {\n        return accessControlEngine.listPolicies(listOptions);\n      },\n\n      async checkAccess(request) {\n        return accessControlEngine.checkAccess(request);\n      },\n    },\n\n    api: {\n      get router() {\n        return sharedSpaceApi.router;\n      },\n      async handleRequest(request) {\n        return sharedSpaceApi.handleRequest(request);\n      },\n      handleWebSocketConnect(connection) {\n        return sharedSpaceApi.handleWebSocketConnect(connection);\n      },\n    },\n\n    changeNotifier,\n    clock,\n\n    async close() {\n      if (clockFlushTimer) {\n        clearTimeout(clockFlushTimer);\n        clockFlushTimer = null;\n      }\n      if (pendingClockState && syncStateStore) {\n        await syncStateStore.setHlcClockState(pendingClockState);\n      }\n      await databaseAdapter.close();\n      await objectStorageAdapter.close();\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+import * as _starkeep_storage_adapter from '@starkeep/storage-adapter';
+import { DatabaseAdapter, ObjectStorageAdapter } from '@starkeep/storage-adapter';
+import { StarkeepId, CreateDataRecordInput, MetadataRow, DataRecord, HLCClock } from '@starkeep/protocol-primitives';
+export { CreateDataRecordInput, DataRecord, HLCTimestamp, StarkeepId } from '@starkeep/protocol-primitives';
+import { IndexQuery, IndexResult } from '@starkeep/query-orchestrator';
+import { ChangeNotifier, SyncStateStore } from '@starkeep/sync-engine';
+import { CreatePolicyInput, AccessPolicy, AccessCheckRequest, AccessCheckResult, AccessPolicyStore, SharingTokenStore, SubjectType } from '@starkeep/access-control';
+import { ApiRouter, ApiRequest, ApiResponse, WebSocketConnection, ApiSubject, AppSpecificOperations } from '@starkeep/shared-space-api';
+
+/**
+ * Input to `data.putWithFile` / `data.putWithLocalFile` — the file-bytes /
+ * content-hash / object-storage-key / size / mimeType are filled in by the
+ * SDK from the supplied bytes, so callers only specify the metadata they
+ * choose explicitly.
+ */
+type DataPutInput = Omit<CreateDataRecordInput, "contentHash" | "objectStorageKey" | "mimeType" | "sizeBytes"> & {
+    /**
+     * Optional per-category metadata row to write atomically with the
+     * records-table row. Columns are defined by the record's category entry in
+     * `CATEGORIES` (category = `categoryOf(type)`); `other` records have no
+     * metadata table. The SDK supplies the `recordId` itself — callers omit it.
+     */
+    metadata?: Omit<MetadataRow, "recordId">;
+};
+interface DataOperations {
+    putWithFile(input: DataPutInput, file: Uint8Array, contentType: string): Promise<DataRecord>;
+    putWithLocalFile(input: DataPutInput, filePath: string, contentType: string): Promise<DataRecord>;
+    /**
+     * Write a record for a blob that has already been placed in object storage
+     * (e.g. via a presigned PUT upload). The caller supplies the content hash,
+     * the resulting object-storage key, the byte length, and the mime type;
+     * the SDK does not re-read the bytes. Use this when the upload path is
+     * external to the SDK (e.g. browser → S3 → cloud-data-server confirm).
+     */
+    putWithExistingBlob(input: DataPutInput, blob: {
+        contentHash: string;
+        objectStorageKey: string;
+        sizeBytes: number;
+        mimeType: string;
+    }): Promise<DataRecord>;
+    get(recordId: StarkeepId): Promise<DataRecord | null>;
+    /**
+     * Update tracked record metadata (parentId, originalFilename, mimeType). All
+     * data-bearing fields are derived from the underlying file; to change them,
+     * upload a new file via `putWithFile`. The metadata row, if any, is updated
+     * by `putMetadata`.
+     */
+    update(recordId: StarkeepId, patch: Partial<Pick<DataRecord, "originalFilename" | "parentId">>): Promise<DataRecord>;
+    delete(recordId: StarkeepId): Promise<void>;
+    query(params: {
+        type?: string;
+        filters?: _starkeep_storage_adapter.Filter[];
+    }): Promise<DataRecord[]>;
+    /** Write (insert-or-replace) a per-type metadata row. */
+    putMetadata(typeId: string, row: MetadataRow): Promise<void>;
+    /** Read a per-type metadata row by recordId. */
+    getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
+    /** Batch-read per-type metadata rows. */
+    getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
+}
+interface IndexOperations {
+    search(query: IndexQuery): Promise<IndexResult>;
+}
+interface AccessControlOperations {
+    createPolicy(input: CreatePolicyInput): Promise<AccessPolicy>;
+    revokePolicy(policyId: StarkeepId): Promise<void>;
+    listPolicies(options?: {
+        subjectId?: string;
+        resourceId?: string;
+    }): Promise<AccessPolicy[]>;
+    checkAccess(request: AccessCheckRequest): Promise<AccessCheckResult>;
+}
+interface ApiOperations {
+    readonly router: ApiRouter;
+    handleRequest(request: ApiRequest): Promise<ApiResponse>;
+    handleWebSocketConnect(connection: WebSocketConnection): () => void;
+}
+
+interface StarkeepSdk {
+    readonly data: DataOperations;
+    readonly index: IndexOperations;
+    readonly accessControl: AccessControlOperations;
+    readonly api: ApiOperations;
+    /**
+     * Broadcast channel for record-level events. The SDK emits
+     * `local-change-recorded` on every write; the sync supervisor forwards
+     * `local-data-synced` from its per-app engines onto this same notifier so
+     * subscribers (sharedSpaceApi, SSE clients) see one unified stream.
+     */
+    readonly changeNotifier: ChangeNotifier;
+    /** The clock backing this SDK — exposed so the supervisor can share it. */
+    readonly clock: HLCClock;
+    close(): Promise<void>;
+}
+interface StarkeepSdkOptions {
+    readonly databaseAdapter: DatabaseAdapter;
+    readonly objectStorageAdapter: ObjectStorageAdapter;
+    /** Backing store for AccessPolicy rows (instance-local). */
+    readonly accessPolicyStore: AccessPolicyStore;
+    /**
+     * Backing store for sharing tokens. Pass `disabledSharingTokenStore()` on
+     * the local-data-server — tokens are issued and validated cloud-side.
+     */
+    readonly sharingTokenStore: SharingTokenStore;
+    readonly ownerId: string;
+    readonly nodeId: string;
+    readonly clock?: HLCClock;
+    /**
+     * Optional state store. The SDK uses it only to seed and persist HLC clock
+     * state (one clock per node). Per-app watermarks are owned by the
+     * supervisor and never touched here.
+     */
+    readonly syncStateStore?: SyncStateStore;
+    /**
+     * Optional change-notifier to inject. When omitted the SDK creates its own.
+     * Callers inject when they want a sibling component (e.g. the local-data-
+     * server's app-specific factory) to emit `local-change-recorded` events
+     * onto the same channel the supervisor subscribes to.
+     */
+    readonly changeNotifier?: ChangeNotifier;
+    readonly subject?: {
+        readonly subjectType: SubjectType;
+        readonly subjectId: string;
+    };
+    /**
+     * Factory for the app-scoped app-specific operations exposed on the
+     * ApiContext. Provided by the harness (local-data-server) since it owns
+     * the syncable-namespace registry and storage layout.
+     */
+    readonly getAppSpecific?: (subject: ApiSubject) => AppSpecificOperations | null;
+}
+
+declare function createStarkeepSdk(options: StarkeepSdkOptions): Promise<StarkeepSdk>;
+
+export { type AccessControlOperations, type ApiOperations, type DataOperations, type IndexOperations, type StarkeepSdk, type StarkeepSdkOptions, createStarkeepSdk };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import * as _starkeep_storage_adapter from '@starkeep/storage-adapter';
+import { DatabaseAdapter, ObjectStorageAdapter } from '@starkeep/storage-adapter';
+import { StarkeepId, CreateDataRecordInput, MetadataRow, DataRecord, HLCClock } from '@starkeep/protocol-primitives';
+export { CreateDataRecordInput, DataRecord, HLCTimestamp, StarkeepId } from '@starkeep/protocol-primitives';
+import { IndexQuery, IndexResult } from '@starkeep/query-orchestrator';
+import { ChangeNotifier, SyncStateStore } from '@starkeep/sync-engine';
+import { CreatePolicyInput, AccessPolicy, AccessCheckRequest, AccessCheckResult, AccessPolicyStore, SharingTokenStore, SubjectType } from '@starkeep/access-control';
+import { ApiRouter, ApiRequest, ApiResponse, WebSocketConnection, ApiSubject, AppSpecificOperations } from '@starkeep/shared-space-api';
+
+/**
+ * Input to `data.putWithFile` / `data.putWithLocalFile` — the file-bytes /
+ * content-hash / object-storage-key / size / mimeType are filled in by the
+ * SDK from the supplied bytes, so callers only specify the metadata they
+ * choose explicitly.
+ */
+type DataPutInput = Omit<CreateDataRecordInput, "contentHash" | "objectStorageKey" | "mimeType" | "sizeBytes"> & {
+    /**
+     * Optional per-category metadata row to write atomically with the
+     * records-table row. Columns are defined by the record's category entry in
+     * `CATEGORIES` (category = `categoryOf(type)`); `other` records have no
+     * metadata table. The SDK supplies the `recordId` itself — callers omit it.
+     */
+    metadata?: Omit<MetadataRow, "recordId">;
+};
+interface DataOperations {
+    putWithFile(input: DataPutInput, file: Uint8Array, contentType: string): Promise<DataRecord>;
+    putWithLocalFile(input: DataPutInput, filePath: string, contentType: string): Promise<DataRecord>;
+    /**
+     * Write a record for a blob that has already been placed in object storage
+     * (e.g. via a presigned PUT upload). The caller supplies the content hash,
+     * the resulting object-storage key, the byte length, and the mime type;
+     * the SDK does not re-read the bytes. Use this when the upload path is
+     * external to the SDK (e.g. browser → S3 → cloud-data-server confirm).
+     */
+    putWithExistingBlob(input: DataPutInput, blob: {
+        contentHash: string;
+        objectStorageKey: string;
+        sizeBytes: number;
+        mimeType: string;
+    }): Promise<DataRecord>;
+    get(recordId: StarkeepId): Promise<DataRecord | null>;
+    /**
+     * Update tracked record metadata (parentId, originalFilename, mimeType). All
+     * data-bearing fields are derived from the underlying file; to change them,
+     * upload a new file via `putWithFile`. The metadata row, if any, is updated
+     * by `putMetadata`.
+     */
+    update(recordId: StarkeepId, patch: Partial<Pick<DataRecord, "originalFilename" | "parentId">>): Promise<DataRecord>;
+    delete(recordId: StarkeepId): Promise<void>;
+    query(params: {
+        type?: string;
+        filters?: _starkeep_storage_adapter.Filter[];
+    }): Promise<DataRecord[]>;
+    /** Write (insert-or-replace) a per-type metadata row. */
+    putMetadata(typeId: string, row: MetadataRow): Promise<void>;
+    /** Read a per-type metadata row by recordId. */
+    getMetadata(typeId: string, recordId: StarkeepId): Promise<MetadataRow | null>;
+    /** Batch-read per-type metadata rows. */
+    getMetadataByIds(typeId: string, recordIds: StarkeepId[]): Promise<Map<StarkeepId, MetadataRow>>;
+}
+interface IndexOperations {
+    search(query: IndexQuery): Promise<IndexResult>;
+}
+interface AccessControlOperations {
+    createPolicy(input: CreatePolicyInput): Promise<AccessPolicy>;
+    revokePolicy(policyId: StarkeepId): Promise<void>;
+    listPolicies(options?: {
+        subjectId?: string;
+        resourceId?: string;
+    }): Promise<AccessPolicy[]>;
+    checkAccess(request: AccessCheckRequest): Promise<AccessCheckResult>;
+}
+interface ApiOperations {
+    readonly router: ApiRouter;
+    handleRequest(request: ApiRequest): Promise<ApiResponse>;
+    handleWebSocketConnect(connection: WebSocketConnection): () => void;
+}
+
+interface StarkeepSdk {
+    readonly data: DataOperations;
+    readonly index: IndexOperations;
+    readonly accessControl: AccessControlOperations;
+    readonly api: ApiOperations;
+    /**
+     * Broadcast channel for record-level events. The SDK emits
+     * `local-change-recorded` on every write; the sync supervisor forwards
+     * `local-data-synced` from its per-app engines onto this same notifier so
+     * subscribers (sharedSpaceApi, SSE clients) see one unified stream.
+     */
+    readonly changeNotifier: ChangeNotifier;
+    /** The clock backing this SDK — exposed so the supervisor can share it. */
+    readonly clock: HLCClock;
+    close(): Promise<void>;
+}
+interface StarkeepSdkOptions {
+    readonly databaseAdapter: DatabaseAdapter;
+    readonly objectStorageAdapter: ObjectStorageAdapter;
+    /** Backing store for AccessPolicy rows (instance-local). */
+    readonly accessPolicyStore: AccessPolicyStore;
+    /**
+     * Backing store for sharing tokens. Pass `disabledSharingTokenStore()` on
+     * the local-data-server — tokens are issued and validated cloud-side.
+     */
+    readonly sharingTokenStore: SharingTokenStore;
+    readonly ownerId: string;
+    readonly nodeId: string;
+    readonly clock?: HLCClock;
+    /**
+     * Optional state store. The SDK uses it only to seed and persist HLC clock
+     * state (one clock per node). Per-app watermarks are owned by the
+     * supervisor and never touched here.
+     */
+    readonly syncStateStore?: SyncStateStore;
+    /**
+     * Optional change-notifier to inject. When omitted the SDK creates its own.
+     * Callers inject when they want a sibling component (e.g. the local-data-
+     * server's app-specific factory) to emit `local-change-recorded` events
+     * onto the same channel the supervisor subscribes to.
+     */
+    readonly changeNotifier?: ChangeNotifier;
+    readonly subject?: {
+        readonly subjectType: SubjectType;
+        readonly subjectId: string;
+    };
+    /**
+     * Factory for the app-scoped app-specific operations exposed on the
+     * ApiContext. Provided by the harness (local-data-server) since it owns
+     * the syncable-namespace registry and storage layout.
+     */
+    readonly getAppSpecific?: (subject: ApiSubject) => AppSpecificOperations | null;
+}
+
+declare function createStarkeepSdk(options: StarkeepSdkOptions): Promise<StarkeepSdk>;
+
+export { type AccessControlOperations, type ApiOperations, type DataOperations, type IndexOperations, type StarkeepSdk, type StarkeepSdkOptions, createStarkeepSdk };

package/dist/index.js

@@ -0,0 +1,273 @@
+// src/sdk.ts
+import {
+  createHLCClock,
+  createDataRecord,
+  dataRecordObjectKey,
+  categoryOf,
+  isCategoryId
+} from "@starkeep/protocol-primitives";
+import { readFile } from "fs/promises";
+import { basename } from "path";
+import { createUnifiedIndex } from "@starkeep/query-orchestrator";
+import { createChangeNotifier } from "@starkeep/sync-engine";
+import { createAccessControlEngine, createEnforcedDatabaseAdapter } from "@starkeep/access-control";
+import { createSharedSpaceApi } from "@starkeep/shared-space-api";
+async function sha256Hex(data) {
+  const copy = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+  const buf = await crypto.subtle.digest("SHA-256", copy);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function metadataCategory(typeOrCategory) {
+  return isCategoryId(typeOrCategory) ? typeOrCategory : categoryOf(typeOrCategory);
+}
+async function createStarkeepSdk(options) {
+  const {
+    databaseAdapter: rawDatabaseAdapter,
+    objectStorageAdapter,
+    accessPolicyStore,
+    sharingTokenStore,
+    ownerId,
+    nodeId,
+    syncStateStore,
+    subject
+  } = options;
+  await rawDatabaseAdapter.init();
+  await objectStorageAdapter.init();
+  const initialHlcState = await syncStateStore?.getHlcClockState() ?? void 0;
+  let pendingClockState = null;
+  let clockFlushTimer = null;
+  const clock = options.clock ?? createHLCClock({
+    nodeId,
+    wallClockFunction: Date.now,
+    initialState: initialHlcState,
+    onTick: syncStateStore ? (state) => {
+      pendingClockState = state;
+      if (clockFlushTimer) return;
+      clockFlushTimer = setTimeout(() => {
+        clockFlushTimer = null;
+        if (pendingClockState) {
+          void syncStateStore.setHlcClockState(pendingClockState);
+        }
+      }, 5e3);
+    } : void 0
+  });
+  const changeNotifier = options.changeNotifier ?? createChangeNotifier();
+  const accessControlEngine = createAccessControlEngine({
+    policyStore: accessPolicyStore,
+    tokenStore: sharingTokenStore,
+    clock,
+    ownerId
+  });
+  await accessControlEngine.loadPolicies();
+  const databaseAdapter = subject ? createEnforcedDatabaseAdapter({
+    databaseAdapter: rawDatabaseAdapter,
+    accessControlEngine,
+    subjectType: subject.subjectType,
+    subjectId: subject.subjectId
+  }) : rawDatabaseAdapter;
+  const unifiedIndex = createUnifiedIndex({ databaseAdapter });
+  function logChange(record) {
+    changeNotifier.emit({
+      eventType: "local-change-recorded",
+      recordIds: [record.id],
+      timestamp: clock.now()
+    });
+  }
+  const sharedSpaceApi = createSharedSpaceApi({
+    databaseAdapter,
+    objectStorageAdapter,
+    clock,
+    ownerId,
+    changeNotifier,
+    getAppSpecific: options.getAppSpecific
+  });
+  async function writeRecordAndMetadata(input, fileBytes, contentType, originalFilename) {
+    const contentHash = await sha256Hex(fileBytes);
+    const objectStorageKey = dataRecordObjectKey(input.type, contentHash);
+    const record = createDataRecord(
+      {
+        ...input,
+        contentHash,
+        objectStorageKey,
+        mimeType: contentType,
+        sizeBytes: fileBytes.length,
+        originalFilename
+      },
+      clock
+    );
+    await databaseAdapter.put(record);
+    if (input.metadata && metadataCategory(input.type) !== "other") {
+      await databaseAdapter.putMetadata(input.type, {
+        ...input.metadata,
+        recordId: record.id
+      });
+    }
+    logChange(record);
+    return record;
+  }
+  return {
+    data: {
+      async putWithFile(input, file, contentType) {
+        const contentHash = await sha256Hex(file);
+        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);
+        await objectStorageAdapter.put(objectStorageKey, file, { contentType });
+        return writeRecordAndMetadata(
+          { ...input, contentHash, objectStorageKey },
+          file,
+          contentType,
+          input.originalFilename ?? null
+        );
+      },
+      async putWithLocalFile(input, filePath, contentType) {
+        const fileBytes = await readFile(filePath);
+        const contentHash = await sha256Hex(fileBytes);
+        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);
+        if (objectStorageAdapter.putSymlink) {
+          await objectStorageAdapter.putSymlink(objectStorageKey, filePath, { contentType });
+        } else {
+          await objectStorageAdapter.put(objectStorageKey, fileBytes, { contentType });
+        }
+        return writeRecordAndMetadata(
+          input,
+          fileBytes,
+          contentType,
+          input.originalFilename ?? basename(filePath)
+        );
+      },
+      async putWithExistingBlob(input, blob) {
+        const record = createDataRecord(
+          {
+            ...input,
+            contentHash: blob.contentHash,
+            objectStorageKey: blob.objectStorageKey,
+            mimeType: blob.mimeType,
+            sizeBytes: blob.sizeBytes,
+            originalFilename: input.originalFilename ?? null
+          },
+          clock
+        );
+        await databaseAdapter.put(record);
+        if (input.metadata) {
+          await databaseAdapter.putMetadata(input.type, {
+            ...input.metadata,
+            recordId: record.id
+          });
+        }
+        logChange(record);
+        return record;
+      },
+      async get(recordId) {
+        const record = await databaseAdapter.get(recordId);
+        if (!record) return null;
+        if (record.deletedAt) return null;
+        return record;
+      },
+      async update(recordId, patch) {
+        const existing = await databaseAdapter.get(recordId);
+        if (!existing) {
+          throw new Error(`No data record found with id ${recordId}`);
+        }
+        const updated = {
+          ...existing,
+          originalFilename: patch.originalFilename ?? existing.originalFilename,
+          parentId: patch.parentId ?? existing.parentId,
+          version: existing.version + 1,
+          updatedAt: clock.now()
+        };
+        await databaseAdapter.put(updated);
+        logChange(updated);
+        return updated;
+      },
+      async delete(recordId) {
+        const existing = await databaseAdapter.get(recordId);
+        if (!existing) return;
+        const ts = clock.now();
+        await databaseAdapter.delete(recordId, ts);
+        await databaseAdapter.deleteMetadata(existing.type, recordId);
+        const tombstone = {
+          ...existing,
+          updatedAt: ts,
+          deletedAt: ts,
+          version: existing.version + 1
+        };
+        logChange(tombstone);
+      },
+      async query(params) {
+        const result = await databaseAdapter.query(params);
+        return result.records;
+      },
+      // `typeId` may be a record's extension or a category id; the adapter
+      // derives the per-category metadata table. The `other` category has no
+      // metadata table, so these are no-ops for it.
+      async putMetadata(typeId, row) {
+        if (metadataCategory(typeId) === "other") return;
+        await databaseAdapter.putMetadata(typeId, row);
+      },
+      async getMetadata(typeId, recordId) {
+        if (metadataCategory(typeId) === "other") return null;
+        return databaseAdapter.getMetadata(typeId, recordId);
+      },
+      async getMetadataByIds(typeId, recordIds) {
+        if (metadataCategory(typeId) === "other") return /* @__PURE__ */ new Map();
+        return databaseAdapter.getMetadataByIds(typeId, recordIds);
+      }
+    },
+    index: {
+      async search(query) {
+        return unifiedIndex.search(query);
+      }
+    },
+    accessControl: {
+      async createPolicy(input) {
+        if (subject) {
+          throw new Error(
+            "createPolicy is not available on an app-scoped SDK. Policies are managed by the admin layer."
+          );
+        }
+        return accessControlEngine.createPolicy(input);
+      },
+      async revokePolicy(policyId) {
+        if (subject) {
+          throw new Error(
+            "revokePolicy is not available on an app-scoped SDK. Policies are managed by the admin layer."
+          );
+        }
+        return accessControlEngine.revokePolicy(policyId);
+      },
+      async listPolicies(listOptions) {
+        return accessControlEngine.listPolicies(listOptions);
+      },
+      async checkAccess(request) {
+        return accessControlEngine.checkAccess(request);
+      }
+    },
+    api: {
+      get router() {
+        return sharedSpaceApi.router;
+      },
+      async handleRequest(request) {
+        return sharedSpaceApi.handleRequest(request);
+      },
+      handleWebSocketConnect(connection) {
+        return sharedSpaceApi.handleWebSocketConnect(connection);
+      }
+    },
+    changeNotifier,
+    clock,
+    async close() {
+      if (clockFlushTimer) {
+        clearTimeout(clockFlushTimer);
+        clockFlushTimer = null;
+      }
+      if (pendingClockState && syncStateStore) {
+        await syncStateStore.setHlcClockState(pendingClockState);
+      }
+      await databaseAdapter.close();
+      await objectStorageAdapter.close();
+    }
+  };
+}
+export {
+  createStarkeepSdk
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import {\n  createHLCClock,\n  createDataRecord,\n  dataRecordObjectKey,\n  categoryOf,\n  isCategoryId,\n  type DataRecord,\n  type MetadataRow,\n} from \"@starkeep/protocol-primitives\";\nimport { readFile } from \"node:fs/promises\";\nimport { basename } from \"node:path\";\nasync function sha256Hex(data: Uint8Array | Buffer): Promise<string> {\n  const copy = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;\n  const buf = await crypto.subtle.digest(\"SHA-256\", copy);\n  return Array.from(new Uint8Array(buf))\n    .map((b) => b.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n}\nimport { createUnifiedIndex } from \"@starkeep/query-orchestrator\";\nimport { createChangeNotifier } from \"@starkeep/sync-engine\";\nimport { createAccessControlEngine, createEnforcedDatabaseAdapter } from \"@starkeep/access-control\";\nimport { createSharedSpaceApi } from \"@starkeep/shared-space-api\";\nimport type {\n  StarkeepSdk,\n  StarkeepSdkOptions,\n  DataPutInput,\n} from \"./types.js\";\n\n// Resolve a record's type/extension (or a category id) to its metadata\n// category. `other` has no metadata table, so callers skip persistence for it.\nfunction metadataCategory(typeOrCategory: string): string {\n  return isCategoryId(typeOrCategory) ? typeOrCategory : categoryOf(typeOrCategory);\n}\n\nexport async function createStarkeepSdk(\n  options: StarkeepSdkOptions,\n): Promise<StarkeepSdk> {\n  const {\n    databaseAdapter: rawDatabaseAdapter,\n    objectStorageAdapter,\n    accessPolicyStore,\n    sharingTokenStore,\n    ownerId,\n    nodeId,\n    syncStateStore,\n    subject,\n  } = options;\n\n  await rawDatabaseAdapter.init();\n  await objectStorageAdapter.init();\n\n  // Seed the clock from persisted state and debounce write-back on tick,\n  // so a restart resumes with an HLC causally after anything we emitted.\n  // The clock state is global (one clock per node) — the supervisor's\n  // per-app cursors live alongside it in the same store but are owned\n  // elsewhere.\n  const initialHlcState =\n    (await syncStateStore?.getHlcClockState()) ?? undefined;\n  let pendingClockState: { wallTime: number; counter: number } | null = null;\n  let clockFlushTimer: NodeJS.Timeout | null = null;\n  const clock =\n    options.clock ??\n    createHLCClock({\n      nodeId,\n      wallClockFunction: Date.now,\n      initialState: initialHlcState,\n      onTick: syncStateStore\n        ? (state) => {\n            pendingClockState = state;\n            if (clockFlushTimer) return;\n            clockFlushTimer = setTimeout(() => {\n              clockFlushTimer = null;\n              if (pendingClockState) {\n                void syncStateStore.setHlcClockState(pendingClockState);\n              }\n            }, 5000);\n          }\n        : undefined,\n    });\n\n  // One shared change notifier. Writes emit `local-change-recorded`; the\n  // supervisor's per-app sync engines forward their own pull/conflict events\n  // onto this same notifier so consumers (sharedSpaceApi, SSE clients) see\n  // one unified stream. Callers may inject a notifier (e.g. the local-data-\n  // server hoists it to share with the app-specific factory, which emits\n  // its own local-change events tagged with the writing app's id).\n  const changeNotifier = options.changeNotifier ?? createChangeNotifier();\n\n  // When a subject is provided, wrap the adapter so every operation is\n  // gated by access control and the private-storage structural rule.\n  const accessControlEngine = createAccessControlEngine({\n    policyStore: accessPolicyStore,\n    tokenStore: sharingTokenStore,\n    clock,\n    ownerId,\n  });\n  await accessControlEngine.loadPolicies();\n\n  const databaseAdapter = subject\n    ? createEnforcedDatabaseAdapter({\n        databaseAdapter: rawDatabaseAdapter,\n        accessControlEngine,\n        subjectType: subject.subjectType,\n        subjectId: subject.subjectId,\n      })\n    : rawDatabaseAdapter;\n\n  const unifiedIndex = createUnifiedIndex({ databaseAdapter });\n\n  /**\n   * Emit a `local-change-recorded` event for a write. The supervisor wakes its\n   * exchange loop in response; the records-table row itself is the durable\n   * source of truth for what to ship (no separate change log).\n   */\n  function logChange(record: DataRecord): void {\n    changeNotifier.emit({\n      eventType: \"local-change-recorded\",\n      recordIds: [record.id],\n      timestamp: clock.now(),\n    });\n  }\n\n  const sharedSpaceApi = createSharedSpaceApi({\n    databaseAdapter,\n    objectStorageAdapter,\n    clock,\n    ownerId,\n    changeNotifier,\n    getAppSpecific: options.getAppSpecific,\n  });\n\n  async function writeRecordAndMetadata(\n    input: DataPutInput,\n    fileBytes: Uint8Array,\n    contentType: string,\n    originalFilename: string | null,\n  ): Promise<DataRecord> {\n    const contentHash = await sha256Hex(fileBytes);\n    const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n    const record = createDataRecord(\n      {\n        ...input,\n        contentHash,\n        objectStorageKey,\n        mimeType: contentType,\n        sizeBytes: fileBytes.length,\n        originalFilename,\n      },\n      clock,\n    );\n    await databaseAdapter.put(record);\n    if (input.metadata && metadataCategory(input.type) !== \"other\") {\n      await databaseAdapter.putMetadata(input.type, {\n        ...input.metadata,\n        recordId: record.id,\n      });\n    }\n    logChange(record);\n    return record;\n  }\n\n  return {\n    data: {\n      async putWithFile(input, file, contentType) {\n        const contentHash = await sha256Hex(file);\n        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n        await objectStorageAdapter.put(objectStorageKey, file, { contentType });\n        return writeRecordAndMetadata(\n          { ...input, contentHash, objectStorageKey } as DataPutInput,\n          file,\n          contentType,\n          input.originalFilename ?? null,\n        );\n      },\n\n      async putWithLocalFile(input, filePath, contentType) {\n        const fileBytes = await readFile(filePath);\n        const contentHash = await sha256Hex(fileBytes);\n        const objectStorageKey = dataRecordObjectKey(input.type, contentHash);\n\n        if (objectStorageAdapter.putSymlink) {\n          await objectStorageAdapter.putSymlink(objectStorageKey, filePath, { contentType });\n        } else {\n          await objectStorageAdapter.put(objectStorageKey, fileBytes, { contentType });\n        }\n\n        return writeRecordAndMetadata(\n          input,\n          fileBytes,\n          contentType,\n          input.originalFilename ?? basename(filePath),\n        );\n      },\n\n      async putWithExistingBlob(input, blob) {\n        // Bytes are already in object storage (uploaded out-of-band, e.g. via\n        // a presigned PUT). Skip the upload + re-hash; trust the caller's\n        // contentHash and sizeBytes. The records-table row is otherwise\n        // identical to what putWithFile would produce.\n        const record = createDataRecord(\n          {\n            ...input,\n            contentHash: blob.contentHash,\n            objectStorageKey: blob.objectStorageKey,\n            mimeType: blob.mimeType,\n            sizeBytes: blob.sizeBytes,\n            originalFilename: input.originalFilename ?? null,\n          } as DataPutInput as never,\n          clock,\n        );\n        await databaseAdapter.put(record);\n        if (input.metadata) {\n          await databaseAdapter.putMetadata(input.type, {\n            ...input.metadata,\n            recordId: record.id,\n          });\n        }\n        logChange(record);\n        return record;\n      },\n\n      async get(recordId) {\n        const record = await databaseAdapter.get(recordId);\n        if (!record) return null;\n        if (record.deletedAt) return null;\n        return record;\n      },\n\n      async update(recordId, patch) {\n        const existing = await databaseAdapter.get(recordId);\n        if (!existing) {\n          throw new Error(`No data record found with id ${recordId}`);\n        }\n        const updated: DataRecord = {\n          ...existing,\n          originalFilename: patch.originalFilename ?? existing.originalFilename,\n          parentId: patch.parentId ?? existing.parentId,\n          version: existing.version + 1,\n          updatedAt: clock.now(),\n        };\n        await databaseAdapter.put(updated);\n        logChange(updated);\n        return updated;\n      },\n\n      async delete(recordId) {\n        const existing = await databaseAdapter.get(recordId);\n        if (!existing) return;\n        const ts = clock.now();\n        await databaseAdapter.delete(recordId, ts);\n        await databaseAdapter.deleteMetadata(existing.type, recordId);\n        const tombstone: DataRecord = {\n          ...existing,\n          updatedAt: ts,\n          deletedAt: ts,\n          version: existing.version + 1,\n        };\n        logChange(tombstone);\n      },\n\n      async query(params) {\n        const result = await databaseAdapter.query(params);\n        return result.records;\n      },\n\n      // `typeId` may be a record's extension or a category id; the adapter\n      // derives the per-category metadata table. The `other` category has no\n      // metadata table, so these are no-ops for it.\n      async putMetadata(typeId: string, row: MetadataRow) {\n        if (metadataCategory(typeId) === \"other\") return;\n        await databaseAdapter.putMetadata(typeId, row);\n      },\n\n      async getMetadata(typeId, recordId) {\n        if (metadataCategory(typeId) === \"other\") return null;\n        return databaseAdapter.getMetadata(typeId, recordId);\n      },\n\n      async getMetadataByIds(typeId, recordIds) {\n        if (metadataCategory(typeId) === \"other\") return new Map();\n        return databaseAdapter.getMetadataByIds(typeId, recordIds);\n      },\n    },\n\n    index: {\n      async search(query) {\n        return unifiedIndex.search(query);\n      },\n    },\n\n    accessControl: {\n      async createPolicy(input) {\n        if (subject) {\n          throw new Error(\n            \"createPolicy is not available on an app-scoped SDK. Policies are managed by the admin layer.\",\n          );\n        }\n        return accessControlEngine.createPolicy(input);\n      },\n\n      async revokePolicy(policyId) {\n        if (subject) {\n          throw new Error(\n            \"revokePolicy is not available on an app-scoped SDK. Policies are managed by the admin layer.\",\n          );\n        }\n        return accessControlEngine.revokePolicy(policyId);\n      },\n\n      async listPolicies(listOptions) {\n        return accessControlEngine.listPolicies(listOptions);\n      },\n\n      async checkAccess(request) {\n        return accessControlEngine.checkAccess(request);\n      },\n    },\n\n    api: {\n      get router() {\n        return sharedSpaceApi.router;\n      },\n      async handleRequest(request) {\n        return sharedSpaceApi.handleRequest(request);\n      },\n      handleWebSocketConnect(connection) {\n        return sharedSpaceApi.handleWebSocketConnect(connection);\n      },\n    },\n\n    changeNotifier,\n    clock,\n\n    async close() {\n      if (clockFlushTimer) {\n        clearTimeout(clockFlushTimer);\n        clockFlushTimer = null;\n      }\n      if (pendingClockState && syncStateStore) {\n        await syncStateStore.setHlcClockState(pendingClockState);\n      }\n      await databaseAdapter.close();\n      await objectStorageAdapter.close();\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@starkeep/sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starkeep-dev/starkeep-core.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/starkeep-dev/starkeep-core/tree/main/packages/sdk",
+  "dependencies": {
+    "@starkeep/protocol-primitives": "0.1.0",
+    "@starkeep/storage-adapter": "0.1.0",
+    "@starkeep/access-control": "0.1.0",
+    "@starkeep/sync-engine": "0.1.0",
+    "@starkeep/shared-space-api": "0.1.0",
+    "@starkeep/query-orchestrator": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/"
+  }
+}