@brokr/sdk 1.0.0 → 2.0.0

package/dist/src/storage/client.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Brokr SDK — Storage Client
+ *
+ * Full CRUD for R2-backed object storage via the Brokr gateway.
+ */
+import type { StorageFile, UploadedFile, UploadParams, ListParams, ListResult, FileMetadata } from './types';
+export declare class BrokrStorageClient {
+    private readonly _token;
+    private readonly _gatewayUrl;
+    constructor(_token: string | undefined, _gatewayUrl: string);
+    /**
+     * Upload a file and return the stable key plus an immediate access URL.
+     *
+     * The key is the canonical identifier to persist in your app.
+     * The URL is a fresh access URL generated for immediate use.
+     *
+     * Accepts either:
+     * - Object form: `upload({ file, path?, contentType? })`
+     * - Legacy 3-arg form: `upload(data, filename, contentType?)` (backward compat)
+     */
+    upload(params: UploadParams): Promise<UploadedFile>;
+    /** @deprecated Use `upload({ file, path, contentType })` instead. */
+    upload(data: Uint8Array | string | Blob, filename: string, contentType?: string): Promise<UploadedFile>;
+    /**
+     * Get a presigned download URL for a stored object.
+     */
+    signedUrl(key: string, options?: {
+        expiresIn?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** Low-level escape hatch. Most apps should call upload() instead. */
+    signUpload(params: {
+        fileName: string;
+        contentType?: string;
+    }): Promise<{
+        url: string;
+        key: string;
+    }>;
+    /**
+     * Initiate a multipart upload via the gateway.
+     */
+    private _initiateMultipart;
+    /**
+     * Get a presigned URL for uploading a single part.
+     */
+    private _signPartUpload;
+    /**
+     * Complete a multipart upload with part ETags.
+     */
+    private _completeMultipart;
+    /**
+     * Abort a multipart upload, cleaning up uploaded parts.
+     */
+    private _abortMultipart;
+    /**
+     * Upload a large file using multipart upload.
+     * Splits the file into parts, uploads each with retry, then completes.
+     */
+    private _uploadMultipart;
+    /**
+     * List objects by prefix with pagination.
+     */
+    list(params?: ListParams): Promise<ListResult>;
+    /**
+     * Delete an object by key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Copy an object from one key to another.
+     */
+    copy(from: string, to: string): Promise<StorageFile>;
+    /**
+     * Move an object (copy then delete source).
+     */
+    move(from: string, to: string): Promise<StorageFile>;
+    /**
+     * Check if an object exists.
+     */
+    /**
+     * Check if an object exists.
+     *
+     * Returns `false` on any error (not-found, rate-limit, network).
+     * This preserves backwards compatibility — `if (await brokr.storage.exists(key))`
+     * must never throw in user code that doesn't wrap it in try-catch.
+     *
+     * If you need to distinguish "doesn't exist" from "couldn't check",
+     * use `metadata()` instead and catch the error.
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get file metadata without downloading the file.
+     */
+    metadata(key: string): Promise<FileMetadata>;
+    /** @deprecated Use signedUrl() instead. */
+    url(key: string, options?: {
+        expiresIn?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** @deprecated Use signedUrl() instead. */
+    getUrl(key: string, options?: {
+        expiresIn?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** @deprecated Use signUpload() instead. */
+    getUploadUrl(filename: string, contentType?: string): Promise<{
+        url: string;
+        key: string;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/src/storage/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/storage/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,YAAY,EACb,MAAM,SAAS,CAAC;AASjB,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM;IAGtC;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACzD,qEAAqE;IAC/D,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA0E7G;;OAEG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAaxF,sEAAsE;IAChE,UAAU,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAkB3G;;OAEG;YACW,kBAAkB;IAmBhC;;OAEG;YACW,eAAe;IAY7B;;OAEG;YACW,kBAAkB;IAYhC;;OAEG;YACW,eAAe;IAW7B;;;OAGG;YACW,gBAAgB;IAsF9B;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBpD;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAa1D;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAW1D;;OAEG;IACH;;;;;;;;;OASG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB3C;;OAEG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAiBlD,2CAA2C;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAIlF,2CAA2C;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrF,4CAA4C;IACtC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAGlG"}

package/dist/src/storage/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Brokr SDK — Storage types
+ */
+export interface StorageFile {
+    /** The stable object key — use this to retrieve the file later. */
+    key: string;
+    /** Immediate access URL for reading the file. This can be regenerated from the key. */
+    url?: string;
+    /** Original filename. */
+    name?: string;
+    /** File size in bytes. */
+    size?: number;
+    /** Content type (MIME). */
+    type?: string;
+}
+export interface UploadedFile extends StorageFile {
+    /** Immediate access URL for reading the file. Persist the key, not the URL. */
+    url: string;
+    /** Final object name/key segment used for the upload. */
+    name: string;
+    /** Uploaded file size in bytes, when it can be determined locally. */
+    size?: number;
+    /** Final content type sent during upload. */
+    type: string;
+}
+export interface UploadParams {
+    /** File data to upload. */
+    file: Blob | Uint8Array | string;
+    /** Optional path/key for the file. If omitted, auto-generated. */
+    path?: string;
+    /** Content type override. */
+    contentType?: string;
+}
+export interface ListParams {
+    /** Filter by key prefix. */
+    prefix?: string;
+    /** Maximum number of keys to return (default 100, max 1000). */
+    maxKeys?: number;
+    /** Pagination cursor from a previous list call. */
+    cursor?: string;
+}
+export interface ListResult {
+    files: Array<{
+        key: string;
+        size: number;
+        lastModified: string;
+    }>;
+    nextCursor?: string;
+}
+export interface FileMetadata {
+    key: string;
+    size: number;
+    contentType: string;
+    lastModified: string;
+}
+/** @deprecated Use StorageFile instead. */
+export interface UploadResult {
+    key: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;IACjC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb"}