@clonde/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @clonde/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLONDE's app API for JavaScript and TypeScript. Replace your storage
+provider's calls with these: CLONDE picks the bucket for each file by the
+policies in your dashboard, can move it later, and you keep the same key.
+
+File bytes never pass through CLONDE. Uploads go straight to the chosen
+bucket with pre-signed URLs (in parts for large files), and file links
+redirect to wherever the file is now.
+
+Works with fetch: Node 18+, browsers, React Native, Deno, Bun. No dependencies.
+
+## Set up
+
+In CLONDE's dashboard: **Apps → New App**, choose the backends it may use,
+then **New key**. Keep the key on your server as `CLONDE_APP_KEY`.
+
+```ts
+import { Clonde } from "@clonde/sdk";
+
+const clonde = new Clonde({ apiKey: process.env.CLONDE_APP_KEY!, baseUrl: "https://api.clonde.io" });
+```
+
+## Upload from your server
+
+```ts
+const file = await clonde.upload("posts/8812/photo.jpg", bytes, { contentType: "image/jpeg" });
+file.link       // permanent link for <img src>; follows the file if it moves
+file.placement  // { backend: "R2 photos", provider: "s3", ... }
+file.decidedBy  // "Photos on R2" — the policy that chose it
+```
+
+## Upload from a phone or browser
+
+Your server asks CLONDE where the file goes and hands the URL to the client,
+which uploads straight to the bucket:
+
+```ts
+// server
+const intent = await clonde.createUpload({ key, contentType, size });
+// → intent.url / intent.headers (or intent.multipart for files over 100 MB)
+
+// client
+await fetch(intent.url, { method: "PUT", headers: intent.headers, body: file });
+
+// server
+const stored = await clonde.completeUpload({ uploadId: intent.uploadId });
+```
+
+For a multipart intent, get part URLs with `clonde.partUrls(uploadId)`, PUT
+each slice of `partSize` bytes, then `completeUpload`. `uploadedParts()`
+resumes an interrupted upload; `abortUpload()` discards it.
+
+## Read, find and delete
+
+```ts
+await clonde.link(key)               // permanent link
+await clonde.signedUrl(key, 600)     // short-lived direct URL (private files)
+await clonde.file(key)               // size, type, where it is now, its trail
+await clonde.trail(key)              // where it has been (also after deletion)
+await clonde.list({ prefix: "posts/" })  // files and the backend each is on
+await clonde.delete(key)             // every copy, on every backend
+```
+
+## Where a file is, and where it has been
+
+`file(key).location` lists the backends holding the file now (primary
+first). `file(key).trail` lists every change, oldest first:
+
+| event | meaning |
+|---|---|
+| `stored` | uploaded through CLONDE; `detail` names the rule that chose the backend |
+| `adopted` | an existing file brought under CLONDE in place |
+| `moved` | moved by a lifecycle rule or a provider move (`fromBackend` → `backend`) |
+| `replaced` | re-uploaded onto a different backend |
+| `old_copy_deleted` | the copy left behind by a move or re-upload was deleted |
+| `deleted` | the file was deleted |
+
+## Errors
+
+Failures throw `ClondeError` with `status` and the server's message. A policy
+that refuses a file (for example, a region rule) comes back as 422 with the
+reasons in the message.

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @clonde/sdk — CLONDE's app API from JavaScript and TypeScript.
+ *
+ * Swap your storage provider's calls for these. CLONDE decides which bucket
+ * each file goes to (by the policies set in its dashboard) and may move it
+ * later; you keep using the same key. File bytes never pass through CLONDE:
+ * uploads go straight to the chosen bucket with pre-signed URLs, and file
+ * links redirect to wherever the file is now.
+ *
+ * Works anywhere with fetch: Node 18+, browsers, React Native, Deno, Bun.
+ * No dependencies.
+ *
+ *   const clonde = new Clonde({ apiKey: process.env.CLONDE_APP_KEY!, baseUrl: "https://api.clonde.io" });
+ *   const file = await clonde.upload("posts/8812/photo.jpg", bytes, { contentType: "image/jpeg" });
+ *   file.link          // put this in <img src>; it follows the file if CLONDE moves it
+ *   file.placement     // which backend it was stored on, and why (file.decidedBy)
+ */
+export interface ClondeOptions {
+    /** An app key from the dashboard (Apps → your app → New key), clk_… */
+    apiKey: string;
+    /** CLONDE's address, e.g. https://api.clonde.io. The API is at <baseUrl>/api/v1. */
+    baseUrl: string;
+    /** For tests or custom runtimes. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface Placement {
+    backendId: string;
+    backend: string;
+    provider: string;
+    region: string | null;
+}
+export interface UploadIntent {
+    uploadId: string;
+    key: string;
+    /** Single upload: PUT the bytes to url with these headers. */
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    expiresInSeconds?: number;
+    /** Multipart upload (large files): get part URLs with partUrls(). */
+    multipart: {
+        partSize: number;
+        partCount: number;
+    } | null;
+    placement: Placement;
+    decidedBy: string;
+    matchedPolicies: {
+        id: string;
+        name: string;
+    }[];
+    link: string;
+}
+export interface StoredFile {
+    fileId: string;
+    key: string;
+    size: number;
+    contentType: string;
+    placement: Placement;
+    decidedBy: string | null;
+    link: string;
+}
+export interface TrailEntry {
+    event: 'stored' | 'adopted' | 'moved' | 'replaced' | 'deleted' | 'old_copy_deleted';
+    at: string;
+    backendId: string | null;
+    backend: string | null;
+    fromBackendId: string | null;
+    fromBackend: string | null;
+    detail: string | null;
+}
+export interface FileInfo {
+    fileId: string;
+    key: string;
+    size: number | null;
+    contentType: string | null;
+    /** Where the file is now: the primary copy first. */
+    location: {
+        backendId: string;
+        backend: string;
+        provider: string;
+        region: string | null;
+        bucket: string;
+        primary: boolean;
+        storageClass: string | null;
+        since: string | null;
+    }[];
+    /** Where it has been: stored, moved, replaced… oldest first. */
+    trail: TrailEntry[];
+    link: string;
+}
+export interface ListedFile {
+    key: string;
+    size: number | null;
+    contentType: string | null;
+    updatedAt: string | null;
+    backendId: string | null;
+    backend: string | null;
+    provider: string | null;
+    region: string | null;
+    copies: number;
+}
+export type Body = Blob | ArrayBuffer | ArrayBufferView | string;
+export interface UploadOptions {
+    contentType?: string;
+    tags?: string[];
+    /** "hot" (default), "warm" or "cold": how often the file will be read. */
+    tier?: 'hot' | 'warm' | 'cold';
+    /** Called as bytes go up: (sent, total). */
+    onProgress?: (sent: number, total: number) => void;
+    /** Parts uploaded at once in a multipart upload (default 4). */
+    concurrency?: number;
+    signal?: AbortSignal;
+}
+export declare class ClondeError extends Error {
+    status: number;
+    body: any;
+    constructor(message: string, status: number, body?: any);
+}
+export declare class Clonde {
+    private readonly api;
+    private readonly base;
+    private readonly key;
+    private readonly http;
+    private linkBase;
+    constructor(options: ClondeOptions);
+    private call;
+    private q;
+    /** The app, its backends and settings. */
+    app(): Promise<{
+        app: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+        linkBase: string;
+        backends: any[];
+        defaultBackendId: string | null;
+        activePolicies: number;
+        multipartThresholdBytes: number;
+    }>;
+    /**
+     * Step 1 of an upload you run yourself (e.g. hand the URL to a phone or a
+     * browser so the bytes go straight from it to the bucket).
+     */
+    createUpload(input: {
+        key: string;
+        contentType?: string;
+        size?: number;
+        tags?: string[];
+        tier?: 'hot' | 'warm' | 'cold';
+        multipart?: boolean;
+    }, signal?: AbortSignal): Promise<UploadIntent>;
+    /** Signed URLs for parts of a multipart upload (up to 1000 at a time; all when partNumbers is omitted). */
+    partUrls(uploadId: string, partNumbers?: number[], signal?: AbortSignal): Promise<{
+        parts: {
+            partNumber: number;
+            url: string;
+        }[];
+        partSize: number;
+        partCount: number;
+        expiresInSeconds: number;
+    }>;
+    /** Parts already in the bucket, to resume an interrupted multipart upload. */
+    uploadedParts(uploadId: string): Promise<{
+        uploaded: {
+            partNumber: number;
+            etag: string;
+            size: number;
+        }[];
+        partSize: number;
+        partCount: number;
+    }>;
+    /** Step 3: the bytes are there. CLONDE checks and records the file. */
+    completeUpload(input: {
+        key?: string;
+        uploadId?: string;
+        parts?: {
+            partNumber: number;
+            etag: string;
+        }[];
+    }, signal?: AbortSignal): Promise<StoredFile>;
+    /** Give up on an upload (and discard any parts already sent). */
+    abortUpload(uploadId: string): Promise<{
+        aborted: boolean;
+    }>;
+    /**
+     * Upload a file in one call: CLONDE places it, the bytes go straight to
+     * that bucket (in parts for large files), and the stored file comes back
+     * with its link and where it was stored.
+     */
+    upload(key: string, body: Body, options?: UploadOptions): Promise<StoredFile>;
+    /**
+     * The permanent link for a file: redirects to wherever the file is now.
+     * Fetches the app's link base once, then works offline.
+     */
+    link(key: string): Promise<string>;
+    /** A short-lived direct URL to the file (for private files). */
+    signedUrl(key: string, expiresInSeconds?: number): Promise<string>;
+    /** One file: size, type, where it is now and where it has been. */
+    file(key: string): Promise<FileInfo>;
+    /** A file's trail, also after it has been deleted. */
+    trail(key: string): Promise<TrailEntry[]>;
+    /** The app's files, each with the backend it's on. Pass `next` back as `after` for the next page. */
+    list(options?: {
+        prefix?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        files: ListedFile[];
+        next: string | null;
+    }>;
+    /** Delete a file from every backend that holds a copy. Deleting a missing file is not an error. */
+    delete(key: string): Promise<void>;
+}
+export default Clonde;

package/dist/index.js

@@ -0,0 +1,196 @@
+/**
+ * @clonde/sdk — CLONDE's app API from JavaScript and TypeScript.
+ *
+ * Swap your storage provider's calls for these. CLONDE decides which bucket
+ * each file goes to (by the policies set in its dashboard) and may move it
+ * later; you keep using the same key. File bytes never pass through CLONDE:
+ * uploads go straight to the chosen bucket with pre-signed URLs, and file
+ * links redirect to wherever the file is now.
+ *
+ * Works anywhere with fetch: Node 18+, browsers, React Native, Deno, Bun.
+ * No dependencies.
+ *
+ *   const clonde = new Clonde({ apiKey: process.env.CLONDE_APP_KEY!, baseUrl: "https://api.clonde.io" });
+ *   const file = await clonde.upload("posts/8812/photo.jpg", bytes, { contentType: "image/jpeg" });
+ *   file.link          // put this in <img src>; it follows the file if CLONDE moves it
+ *   file.placement     // which backend it was stored on, and why (file.decidedBy)
+ */
+export class ClondeError extends Error {
+    constructor(message, status, body = {}) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ClondeError';
+    }
+}
+const sizeOf = (b) => {
+    if (typeof b === 'string')
+        return new TextEncoder().encode(b).byteLength;
+    if (typeof Blob !== 'undefined' && b instanceof Blob)
+        return b.size;
+    if (b instanceof ArrayBuffer)
+        return b.byteLength;
+    return b.byteLength;
+};
+const sliceOf = (b, start, end) => {
+    if (typeof b === 'string')
+        return new TextEncoder().encode(b).subarray(start, end);
+    if (typeof Blob !== 'undefined' && b instanceof Blob)
+        return b.slice(start, end);
+    if (b instanceof ArrayBuffer)
+        return b.slice(start, end);
+    const v = b;
+    return new Uint8Array(v.buffer, v.byteOffset + start, Math.min(end, v.byteLength) - start);
+};
+export class Clonde {
+    constructor(options) {
+        this.linkBase = null;
+        if (!options?.apiKey)
+            throw new Error('Clonde: apiKey is required');
+        if (!options?.baseUrl)
+            throw new Error('Clonde: baseUrl is required');
+        this.key = options.apiKey;
+        this.base = options.baseUrl.replace(/\/+$/, '');
+        this.api = `${this.base}/api/v1`;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error('Clonde: no fetch available; pass options.fetch');
+        this.http = f.bind(globalThis);
+    }
+    async call(method, path, body, signal) {
+        const res = await this.http(`${this.api}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.key}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+            signal,
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            const why = [data.error, ...(data.reasons ?? [])].filter(Boolean).join('; ');
+            throw new ClondeError(why || `${method} ${path} failed (${res.status})`, res.status, data);
+        }
+        return data;
+    }
+    q(key) {
+        return `?key=${encodeURIComponent(key)}`;
+    }
+    /** The app, its backends and settings. */
+    app() {
+        return this.call('GET', '/app');
+    }
+    /**
+     * Step 1 of an upload you run yourself (e.g. hand the URL to a phone or a
+     * browser so the bytes go straight from it to the bucket).
+     */
+    createUpload(input, signal) {
+        return this.call('POST', '/uploads', input, signal);
+    }
+    /** Signed URLs for parts of a multipart upload (up to 1000 at a time; all when partNumbers is omitted). */
+    partUrls(uploadId, partNumbers, signal) {
+        return this.call('POST', '/uploads/parts', { uploadId, ...(partNumbers ? { partNumbers } : {}) }, signal);
+    }
+    /** Parts already in the bucket, to resume an interrupted multipart upload. */
+    uploadedParts(uploadId) {
+        return this.call('GET', `/uploads/parts?uploadId=${encodeURIComponent(uploadId)}`);
+    }
+    /** Step 3: the bytes are there. CLONDE checks and records the file. */
+    completeUpload(input, signal) {
+        return this.call('POST', '/uploads/complete', input, signal);
+    }
+    /** Give up on an upload (and discard any parts already sent). */
+    abortUpload(uploadId) {
+        return this.call('DELETE', `/uploads?uploadId=${encodeURIComponent(uploadId)}`);
+    }
+    /**
+     * Upload a file in one call: CLONDE places it, the bytes go straight to
+     * that bucket (in parts for large files), and the stored file comes back
+     * with its link and where it was stored.
+     */
+    async upload(key, body, options = {}) {
+        const size = sizeOf(body);
+        const contentType = options.contentType
+            ?? (typeof Blob !== 'undefined' && body instanceof Blob && body.type ? body.type : 'application/octet-stream');
+        const intent = await this.createUpload({ key, contentType, size, tags: options.tags, tier: options.tier }, options.signal);
+        try {
+            if (!intent.multipart) {
+                const res = await this.http(intent.url, { method: intent.method || 'PUT', headers: intent.headers, body: body, signal: options.signal });
+                if (!res.ok)
+                    throw new ClondeError(`Upload to ${intent.placement.backend} failed (${res.status})`, res.status);
+                options.onProgress?.(size, size);
+                return await this.completeUpload({ uploadId: intent.uploadId }, options.signal);
+            }
+            const { partSize, partCount } = intent.multipart;
+            let sent = 0;
+            for (let first = 1; first <= partCount; first += 1000) {
+                const numbers = Array.from({ length: Math.min(1000, partCount - first + 1) }, (_, i) => first + i);
+                const { parts } = await this.partUrls(intent.uploadId, numbers, options.signal);
+                const queue = [...parts];
+                const workers = Array.from({ length: Math.max(1, options.concurrency ?? 4) }, async () => {
+                    for (let p = queue.shift(); p; p = queue.shift()) {
+                        const start = (p.partNumber - 1) * partSize;
+                        const chunk = sliceOf(body, start, Math.min(start + partSize, size));
+                        const res = await this.http(p.url, { method: 'PUT', body: chunk, signal: options.signal });
+                        if (!res.ok)
+                            throw new ClondeError(`Part ${p.partNumber} to ${intent.placement.backend} failed (${res.status})`, res.status);
+                        sent += sizeOf(chunk);
+                        options.onProgress?.(sent, size);
+                    }
+                });
+                await Promise.all(workers);
+            }
+            // CLONDE reads the part list from the bucket, so browsers that can't see
+            // ETags work too.
+            return await this.completeUpload({ uploadId: intent.uploadId }, options.signal);
+        }
+        catch (err) {
+            if (intent.multipart)
+                await this.abortUpload(intent.uploadId).catch(() => undefined);
+            throw err;
+        }
+    }
+    /**
+     * The permanent link for a file: redirects to wherever the file is now.
+     * Fetches the app's link base once, then works offline.
+     */
+    async link(key) {
+        if (!this.linkBase)
+            this.linkBase = (await this.app()).linkBase;
+        return `${this.linkBase}/${key.split('/').map(encodeURIComponent).join('/')}`;
+    }
+    /** A short-lived direct URL to the file (for private files). */
+    async signedUrl(key, expiresInSeconds = 3600) {
+        return (await this.call('GET', `/files/url${this.q(key)}&expires=${expiresInSeconds}`)).url;
+    }
+    /** One file: size, type, where it is now and where it has been. */
+    file(key) {
+        return this.call('GET', `/files${this.q(key)}`);
+    }
+    /** A file's trail, also after it has been deleted. */
+    async trail(key) {
+        return (await this.call('GET', `/files/trail${this.q(key)}`)).trail;
+    }
+    /** The app's files, each with the backend it's on. Pass `next` back as `after` for the next page. */
+    list(options = {}) {
+        const params = new URLSearchParams();
+        if (options.prefix)
+            params.set('prefix', options.prefix);
+        if (options.after)
+            params.set('after', options.after);
+        if (options.limit)
+            params.set('limit', String(options.limit));
+        const qs = params.toString();
+        return this.call('GET', `/files/list${qs ? `?${qs}` : ''}`);
+    }
+    /** Delete a file from every backend that holds a copy. Deleting a missing file is not an error. */
+    async delete(key) {
+        try {
+            await this.call('DELETE', `/files${this.q(key)}`);
+        }
+        catch (err) {
+            if (err instanceof ClondeError && err.status === 404)
+                return;
+            throw err;
+        }
+    }
+}
+export default Clonde;

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@clonde/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLONDE's app API: uploads straight to the bucket CLONDE picks, permanent file links, and where each file is stored.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepare": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "devDependencies": { "typescript": "^5.6.0" },
+  "license": "MIT"
+}