@moogodev/client 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @moogodev/client
 
-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.
+Official JavaScript/TypeScript client for Moogo object storage.
+
+## Install
+
+```bash
+npm install @moogodev/client
+```
+
+## Quick Start
+
+```typescript
+import { MoogoClient, createClientFromEnv } from '@moogodev/client';
+
+// Reads from environment variables:
+// MOOGO_API_URL, MOOGO_PROJECT_ID, MOOGO_BUCKET_ACCESS_KEY_ID, MOOGO_BUCKET_SECRET_KEY
+const client = createClientFromEnv();
+
+// Upload with custom Cache-Control
+const response = await client.upload('avatars/user.png', fileBlob, {
+  contentType: 'image/png',
+  cacheControl: 'public, max-age=31536000, immutable',
+  onProgress: (loaded, total) => console.log(`${loaded}/${total}`),
+});
+
+console.log(response.object.public_url);
+```
+
+## Features
+
+- **Full TypeScript support** — complete type definitions for all API responses
+- **Cursor-based pagination** — stable `nextCursor` + `total` for listings
+- **Range requests** — `206 Partial Content`, `416 Range Not Satisfiable`, `If-Range`
+- **Custom Cache-Control** — send `Cache-Control` header on upload to override defaults
+- **Presigned URLs** — GET (download) and PUT (browser direct upload)
+- **Signed uploads** — returns upload URL + object metadata
+- **Bucket operations** — list, create, update, delete, get info, toggle public
+- **Credential management** — list, create, rotate, revoke storage credentials
+- **Rate-limit handling** — `X-RateLimit-Reset` header parsing, `RateLimitedError` with `retryAfter`/`resetAt`
+- **Typed errors** — all API error codes as distinct classes
+- **Zero dependencies** — uses Web Crypto API (native in Node 18+, browsers, edge runtimes)
+- **Works everywhere** — Node 18+, Deno, Bun, Cloudflare Workers, Vercel Edge, browsers (via bundler)
+
+## Documentation
+
+- [Full API Reference](https://moogo.dev/docs/javascript-client)
+- [Object Storage API](https://moogo.dev/docs/object-storage)
+- [Rate Limits](https://moogo.dev/docs/limits)
+- [Error Codes](https://moogo.dev/docs/errors)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Moogo JavaScript/TypeScript Client
+ * Official client for Moogo object storage API.
+ */
+import type { ClientConfig, Bucket, CreateBucketRequest, UpdateBucketRequest, BucketInfoResponse, ObjectResponse, UploadResponse, ListObjectsQuery, ListObjectsResponse, PresignedUrlRequest, PresignedUrlResponse, SignedUploadResponse, StorageCredential, CreateCredentialRequest, CreateCredentialResponse, RotateCredentialResponse } from './types.js';
+/**
+ * Moogo client for object storage operations.
+ *
+ * @example
+ * ```typescript
+ * import { MoogoClient } from '@moogodev/client';
+ *
+ * const client = new MoogoClient({
+ *   baseUrl: 'https://api.moogo.dev',
+ *   projectId: 'your-project-id',
+ *   accessKeyId: 'your-access-key',
+ *   secretKey: 'your-secret-key',
+ * });
+ *
+ * // Upload a file
+ * const response = await client.upload('avatars/user.png', fileBlob, {
+ *   contentType: 'image/png',
+ *   cacheControl: 'public, max-age=31536000, immutable',
+ * });
+ *
+ * // List objects
+ * const { objects, nextCursor } = await client.listObjects({ prefix: 'avatars/' });
+ * ```
+ */
+export declare class MoogoClient {
+    private readonly baseUrl;
+    private readonly projectId;
+    private readonly accessKeyId;
+    private readonly secretKey;
+    private readonly fetchImpl;
+    private readonly timeout;
+    constructor(config: ClientConfig);
+    /** Build the bucket catalog path */
+    private getCatalogPath;
+    /** Build the credentials path */
+    private getCredentialsPath;
+    /** Create authorization header using AWS Signature V4-like scheme */
+    private createAuthHeader;
+    private hashBody;
+    private hashString;
+    private getSigningKey;
+    private hmacSha256;
+    /** Execute a request with auth and error handling */
+    private request;
+    /** List all buckets in the project */
+    listBuckets(): Promise<Bucket[]>;
+    /** Get bucket info including usage stats */
+    getBucketInfo(bucketId: string): Promise<BucketInfoResponse>;
+    /** Create a new bucket */
+    createBucket(request: CreateBucketRequest): Promise<Bucket>;
+    /** Update bucket settings */
+    updateBucket(bucketId: string, request: UpdateBucketRequest): Promise<Bucket>;
+    /** Delete a bucket and all its objects */
+    deleteBucket(bucketId: string): Promise<void>;
+    /** Toggle bucket public/private (fans out to all objects) */
+    setBucketPublic(bucketId: string, isPublic: boolean): Promise<Bucket>;
+    /**
+     * Upload an object to a bucket.
+     *
+     * @param key - Object key (path within bucket)
+     * @param data - File data (Blob, File, Uint8Array, ReadableStream, or string)
+     * @param options - Upload options
+     */
+    upload(key: string, data: Blob | File | Uint8Array | ReadableStream<Uint8Array> | string, options?: {
+        bucket?: string;
+        contentType?: string;
+        cacheControl?: string;
+        onProgress?: (loaded: number, total: number) => void;
+        signal?: AbortSignal;
+    }): Promise<UploadResponse>;
+    /** Wrap a Blob with progress tracking */
+    private wrapWithProgress;
+    /** Download an object */
+    download(key: string, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+        range?: {
+            start: number;
+            end?: number;
+        };
+    }): Promise<Response>;
+    /** Download object as blob */
+    downloadBlob(key: string, options?: Parameters<typeof this.download>[1]): Promise<Blob>;
+    /** Download object as text */
+    downloadText(key: string, options?: Parameters<typeof this.download>[1]): Promise<string>;
+    /** Download object as ArrayBuffer */
+    downloadArrayBuffer(key: string, options?: Parameters<typeof this.download>[1]): Promise<ArrayBuffer>;
+    /** Get object metadata (HEAD request) */
+    headObject(key: string, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        headers: Headers;
+        exists: boolean;
+    }>;
+    /** Delete an object */
+    deleteObject(key: string, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** List objects in a bucket */
+    listObjects(query?: ListObjectsQuery): Promise<ListObjectsResponse>;
+    /** Get a presigned URL for an object */
+    getPresignedUrl(key: string, request: PresignedUrlRequest, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+    }): Promise<PresignedUrlResponse>;
+    /** Create a signed upload URL (returns upload URL + object metadata) */
+    createSignedUpload(key: string, request: PresignedUrlRequest & {
+        content_type?: string;
+    }, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+    }): Promise<SignedUploadResponse>;
+    /** Update object metadata (visibility, key) */
+    updateObject(key: string, updates: {
+        is_public?: boolean;
+        new_key?: string;
+    }, options?: {
+        bucket?: string;
+        signal?: AbortSignal;
+    }): Promise<ObjectResponse>;
+    /** List storage credentials */
+    listCredentials(): Promise<StorageCredential[]>;
+    /** Create a new storage credential */
+    createCredential(request: CreateCredentialRequest): Promise<CreateCredentialResponse>;
+    /** Rotate a credential (generates new secret) */
+    rotateCredential(credentialId: string): Promise<RotateCredentialResponse>;
+    /** Revoke a credential */
+    revokeCredential(credentialId: string): Promise<void>;
+    /** Get the public URL for an object (if published) */
+    getPublicUrl(key: string, publicUrlBase?: string): string;
+    /** Get the authenticated download URL for an object */
+    getAuthenticatedUrl(key: string): string;
+    /** Check if an object exists (efficient HEAD) */
+    objectExists(key: string, options?: {
+        bucket?: string;
+    }): Promise<boolean>;
+    /** Get object size without downloading */
+    getObjectSize(key: string, options?: {
+        bucket?: string;
+    }): Promise<number | null>;
+    /** Get object ETag */
+    getObjectETag(key: string, options?: {
+        bucket?: string;
+    }): Promise<string | null>;
+}
+/** Convenience function to create a client from environment variables */
+export declare function createClientFromEnv(env?: Record<string, string | undefined>): MoogoClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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