@w3kits/sdk 0.1.0

package/dist/r2-client.js

@@ -0,0 +1,56 @@
+export const W3KITS_STORAGE_CAPABILITY_DESCRIPTOR_VERSION = "w3kits.storage.capability.v1";
+/**
+ * Creates the SDK-owned descriptor shape consumed by plugin/runtime bridges.
+ */
+export function createW3KitsStorageCapabilityDescriptor(input) {
+    return {
+        version: W3KITS_STORAGE_CAPABILITY_DESCRIPTOR_VERSION,
+        visibleRoot: input.capability.root,
+        capability: input.capability,
+        r2: input.r2,
+        auth: {
+            mode: "runtime-session",
+            header: "x-w3kits-runtime-session",
+        },
+        localFirst: {
+            enabled: input.localFirstEnabled !== false,
+            store: "indexeddb-opfs",
+            commit: {
+                interactiveSuccess: "local",
+                remoteSync: "background",
+            },
+            flushPolicy: {
+                onChange: true,
+                debounceMs: 2000,
+                lifecycleEvents: [
+                    "visibilitychange",
+                    "pagehide",
+                    "run-complete",
+                    "daemon-stop",
+                    "daemon-crash",
+                ],
+                highFrequencyPolling: false,
+            },
+        },
+        sync: {
+            commitSemantics: "local-durable-first",
+            largeBodyThresholdBytes: input.largeBodyThresholdBytes ?? 4 * 1024 * 1024,
+        },
+    };
+}
+/**
+ * Builds a path-style R2 object URL from a scoped descriptor.
+ */
+export function r2ObjectUrl(descriptor, key) {
+    const endpoint = descriptor.endpoint.replace(/\/+$/u, "");
+    const cleanPrefix = descriptor.prefix.replace(/^\/+|\/+$/gu, "");
+    const cleanKey = key.replace(/^\/+/u, "");
+    const objectKey = [cleanPrefix, cleanKey]
+        .filter((segment) => segment.length > 0)
+        .join("/");
+    return `${endpoint}/${encodeURIComponent(descriptor.bucket)}/${objectKey
+        .split("/")
+        .map(encodeURIComponent)
+        .join("/")}`;
+}
+//# sourceMappingURL=r2-client.js.map

package/dist/r2-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-client.js","sourceRoot":"","sources":["../src/r2-client.ts"],"names":[],"mappings":"AAoCA,MAAM,CAAC,MAAM,4CAA4C,GACvD,8BAA8B,CAAC;AAsCjC;;GAEG;AACH,MAAM,UAAU,uCAAuC,CACrD,KAA6C;IAE7C,OAAO;QACL,OAAO,EAAE,4CAA4C;QACrD,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI;QAClC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE;YACJ,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,0BAA0B;SACnC;QACD,UAAU,EAAE;YACV,OAAO,EAAE,KAAK,CAAC,iBAAiB,KAAK,KAAK;YAC1C,KAAK,EAAE,gBAAgB;YACvB,MAAM,EAAE;gBACN,kBAAkB,EAAE,OAAO;gBAC3B,UAAU,EAAE,YAAY;aACzB;YACD,WAAW,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI;gBAChB,eAAe,EAAE;oBACf,kBAAkB;oBAClB,UAAU;oBACV,cAAc;oBACd,aAAa;oBACb,cAAc;iBACf;gBACD,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,IAAI,EAAE;YACJ,eAAe,EAAE,qBAAqB;YACtC,uBAAuB,EAAE,KAAK,CAAC,uBAAuB,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;SAC1E;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,UAAyE,EACzE,GAAW;IAEX,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC;SACtC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,QAAQ,IAAI,kBAAkB,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,SAAS;SACrE,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,kBAAkB,CAAC;SACvB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACjB,CAAC"}

package/dist/storage/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Defines SDK storage capability contracts and a small local-first flush adapter.
+ * @owner w3kits-sdk
+ * @module sdk
+ * @boundary storage
+ */
+import { InMemoryOperationLog, type LocalFirstVfsClientOptions, type LocalFirstVfsOperation } from "../local-cache.js";
+import { type StorageScope } from "../path-mapping.js";
+export type StorageCapabilityAction = "list" | "get" | "put" | "delete" | "multipart";
+export type StorageCapability = {
+    id: string;
+    userId: string;
+    profileId: string;
+    root: "/home/agent" | `/home/agent/${string}`;
+    actions: StorageCapabilityAction[];
+    expiresAt: string;
+    credentialMode: "temporary-r2-credentials" | "presigned-url";
+};
+export type StorageRemote = {
+    put(input: {
+        key: string;
+        body: Uint8Array;
+        operationId: string;
+    }): Promise<{
+        revision?: string;
+    }>;
+    delete(input: {
+        key: string;
+        operationId: string;
+    }): Promise<{
+        revision?: string;
+    }>;
+};
+/**
+ * Represents auth/capability failures during queued storage flush.
+ */
+export declare class StorageAuthError extends Error {
+    /**
+     * Creates a storage auth error.
+     */
+    constructor(message?: string);
+}
+/**
+ * Minimal local-first storage client for SDK contract tests and future browser adapters.
+ */
+export declare class LocalFirstStorageClient {
+    private readonly options;
+    private readonly remote?;
+    readonly operations: InMemoryOperationLog;
+    /**
+     * Initializes the storage client.
+     */
+    constructor(options: LocalFirstVfsClientOptions & StorageScope, remote?: StorageRemote | undefined);
+    /**
+     * Enqueues a visible-path put operation.
+     */
+    put(visiblePath: string, body: Uint8Array): LocalFirstVfsOperation;
+    /**
+     * Enqueues a visible-path delete operation.
+     */
+    delete(visiblePath: string): LocalFirstVfsOperation;
+    /**
+     * Flushes queued operations through the remote adapter.
+     */
+    flush(): Promise<LocalFirstVfsOperation[]>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,oBAAoB,EAEpB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,KAAK,GACL,KAAK,GACL,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,aAAa,GAAG,eAAe,MAAM,EAAE,CAAC;IAC9C,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,0BAA0B,GAAG,eAAe,CAAC;CAC9D,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,KAAK,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,UAAU,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnC,MAAM,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF,CAAC;AAEF;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC;;OAEG;gBACS,OAAO,SAAiD;CAIrE;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAOhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAP1B,QAAQ,CAAC,UAAU,uBAA8B;IAEjD;;OAEG;gBAEgB,OAAO,EAAE,0BAA0B,GAAG,YAAY,EAClD,MAAM,CAAC,EAAE,aAAa,YAAA;IAGzC;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,sBAAsB;IAWlE;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB;IAUnD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC;CAmDjD"}

package/dist/storage/index.js

@@ -0,0 +1,111 @@
+/**
+ * Defines SDK storage capability contracts and a small local-first flush adapter.
+ * @owner w3kits-sdk
+ * @module sdk
+ * @boundary storage
+ */
+import { InMemoryOperationLog, markQueuedAuthFailure, } from "../local-cache.js";
+import { mapVisiblePathToR2 } from "../path-mapping.js";
+/**
+ * Represents auth/capability failures during queued storage flush.
+ */
+export class StorageAuthError extends Error {
+    /**
+     * Creates a storage auth error.
+     */
+    constructor(message = "Storage capability is unavailable or expired") {
+        super(message);
+        this.name = "StorageAuthError";
+    }
+}
+/**
+ * Minimal local-first storage client for SDK contract tests and future browser adapters.
+ */
+export class LocalFirstStorageClient {
+    options;
+    remote;
+    operations = new InMemoryOperationLog();
+    /**
+     * Initializes the storage client.
+     */
+    constructor(options, remote) {
+        this.options = options;
+        this.remote = remote;
+    }
+    /**
+     * Enqueues a visible-path put operation.
+     */
+    put(visiblePath, body) {
+        const mapping = mapVisiblePathToR2(visiblePath, this.options);
+        return this.operations.enqueue({
+            scopeId: `${mapping.userId}:${mapping.profileId}`,
+            type: "put",
+            bucket: "home",
+            key: mapping.relativeHomePath,
+            bodyRef: `memory:${body.byteLength}:${mapping.r2Key}`,
+        });
+    }
+    /**
+     * Enqueues a visible-path delete operation.
+     */
+    delete(visiblePath) {
+        const mapping = mapVisiblePathToR2(visiblePath, this.options);
+        return this.operations.enqueue({
+            scopeId: `${mapping.userId}:${mapping.profileId}`,
+            type: "delete",
+            bucket: "home",
+            key: mapping.relativeHomePath,
+        });
+    }
+    /**
+     * Flushes queued operations through the remote adapter.
+     */
+    async flush() {
+        if (!this.remote)
+            return this.operations.pending();
+        const flushed = [];
+        for (const operation of this.operations.pending()) {
+            try {
+                const syncing = this.operations.update({
+                    ...operation,
+                    status: "syncing",
+                    attempts: operation.attempts + 1,
+                    updatedAt: new Date().toISOString(),
+                });
+                if (syncing.type === "put") {
+                    await this.remote.put({
+                        key: syncing.key,
+                        body: new Uint8Array(),
+                        operationId: syncing.operationId,
+                    });
+                }
+                else if (syncing.type === "delete") {
+                    await this.remote.delete({
+                        key: syncing.key,
+                        operationId: syncing.operationId,
+                    });
+                }
+                flushed.push(this.operations.update({
+                    ...syncing,
+                    status: "synced",
+                    updatedAt: new Date().toISOString(),
+                }));
+            }
+            catch (error) {
+                if (error instanceof StorageAuthError) {
+                    flushed.push(this.operations.update(markQueuedAuthFailure(operation, this.options)));
+                    continue;
+                }
+                flushed.push(this.operations.update({
+                    ...operation,
+                    status: "failed",
+                    attempts: operation.attempts + 1,
+                    lastError: error instanceof Error ? error.message : "flush_failed",
+                    updatedAt: new Date().toISOString(),
+                }));
+            }
+        }
+        return flushed;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@w3kits/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "description": "Client-first W3Kits SDK for browser, plugin, container, storage, visible path, local cache, R2 capability, and .app file semantics.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./container": {
+      "types": "./dist/container.d.ts",
+      "import": "./dist/container.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./path-mapping": {
+      "types": "./dist/path-mapping.d.ts",
+      "import": "./dist/path-mapping.js"
+    },
+    "./local-cache": {
+      "types": "./dist/local-cache.d.ts",
+      "import": "./dist/local-cache.js"
+    },
+    "./r2-client": {
+      "types": "./dist/r2-client.d.ts",
+      "import": "./dist/r2-client.js"
+    },
+    "./app-file": {
+      "types": "./dist/app-file.d.ts",
+      "import": "./dist/app-file.js"
+    },
+    "./profile-app-file": {
+      "types": "./dist/profile-app-file.d.ts",
+      "import": "./dist/profile-app-file.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "pack:check": "npm pack --dry-run",
+    "prepack": "npm run build",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@workspace/typescript-config": "workspace:*",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}