@moogodev/client 0.0.0-stage → 0.1.0

package/src/errors.ts

@@ -0,0 +1,259 @@
+/**
+ * Error classes for Moogo client.
+ * All errors follow the API error codes.
+ */
+
+export class MoogoError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly detail?: string;
+
+  constructor(code: string, message: string, status: number, detail?: string) {
+    super(message);
+    this.name = 'MoogoError';
+    this.code = code;
+    this.status = status;
+    this.detail = detail;
+    Object.setPrototypeOf(this, MoogoError.prototype);
+  }
+
+  static fromResponse(response: Response, data: any): MoogoError {
+    const error = data?.error;
+    if (error) {
+      return new MoogoError(
+        error.code,
+        error.message,
+        response.status,
+        error.detail
+      );
+    }
+    return new MoogoError(
+      'unknown_error',
+      `HTTP ${response.status}: ${response.statusText}`,
+      response.status
+    );
+  }
+}
+
+/** 400 - Missing or invalid object key */
+export class MissingKeyError extends MoogoError {
+  constructor(detail?: string) {
+    super('missing_key', 'No object key in the path', 400, detail);
+    this.name = 'MissingKeyError';
+    Object.setPrototypeOf(this, MissingKeyError.prototype);
+  }
+}
+
+export class InvalidKeyError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_key', 'Key contains invalid characters', 400, detail);
+    this.name = 'InvalidKeyError';
+    Object.setPrototypeOf(this, InvalidKeyError.prototype);
+  }
+}
+
+export class KeyTooLongError extends MoogoError {
+  constructor(detail?: string) {
+    super('key_too_long', 'Object key exceeds maximum length', 400, detail);
+    this.name = 'KeyTooLongError';
+    Object.setPrototypeOf(this, KeyTooLongError.prototype);
+  }
+}
+
+export class KeyTakenError extends MoogoError {
+  constructor(detail?: string) {
+    super('key_taken', 'An object with that key already exists', 409, detail);
+    this.name = 'KeyTakenError';
+    Object.setPrototypeOf(this, KeyTakenError.prototype);
+  }
+}
+
+export class InvalidBucketError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_bucket', 'Bucket name is not allowed or invalid', 400, detail);
+    this.name = 'InvalidBucketError';
+    Object.setPrototypeOf(this, InvalidBucketError.prototype);
+  }
+}
+
+export class InvalidCursorError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_cursor', 'Cursor is malformed or belongs to a different listing', 400, detail);
+    this.name = 'InvalidCursorError';
+    Object.setPrototypeOf(this, InvalidCursorError.prototype);
+  }
+}
+
+export class InvalidOrderError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_order', 'Unknown order or direction', 400, detail);
+    this.name = 'InvalidOrderError';
+    Object.setPrototypeOf(this, InvalidOrderError.prototype);
+  }
+}
+
+export class BodyTooLargeError extends MoogoError {
+  constructor(detail?: string) {
+    super('body_too_large', 'Request body exceeded the JSON or upload cap', 413, detail);
+    this.name = 'BodyTooLargeError';
+    Object.setPrototypeOf(this, BodyTooLargeError.prototype);
+  }
+}
+
+export class ObjectTooLargeError extends MoogoError {
+  constructor(detail?: string) {
+    super('object_too_large', 'Object over the bucket max size', 413, detail);
+    this.name = 'ObjectTooLargeError';
+    Object.setPrototypeOf(this, ObjectTooLargeError.prototype);
+  }
+}
+
+export class UnsupportedMediaTypeError extends MoogoError {
+  constructor(detail?: string) {
+    super('unsupported_media_type', 'Wrong Content-Type', 415, detail);
+    this.name = 'UnsupportedMediaTypeError';
+    Object.setPrototypeOf(this, UnsupportedMediaTypeError.prototype);
+  }
+}
+
+export class QuotaExceededError extends MoogoError {
+  constructor(detail?: string) {
+    super('quota_exceeded', 'Project or bucket storage would go over quota', 409, detail);
+    this.name = 'QuotaExceededError';
+    Object.setPrototypeOf(this, QuotaExceededError.prototype);
+  }
+}
+
+export class ProjectPausedError extends MoogoError {
+  constructor(detail?: string) {
+    super('project_paused', 'Project is paused', 403, detail);
+    this.name = 'ProjectPausedError';
+    Object.setPrototypeOf(this, ProjectPausedError.prototype);
+  }
+}
+
+export class LinkExpiredError extends MoogoError {
+  constructor(detail?: string) {
+    super('link_expired', 'Signed URL expired', 403, detail);
+    this.name = 'LinkExpiredError';
+    Object.setPrototypeOf(this, LinkExpiredError.prototype);
+  }
+}
+
+export class NotFoundError extends MoogoError {
+  constructor(detail?: string) {
+    super('not_found', 'Bucket/object missing or not published', 404, detail);
+    this.name = 'NotFoundError';
+    Object.setPrototypeOf(this, NotFoundError.prototype);
+  }
+}
+
+export class BucketNotFoundError extends MoogoError {
+  constructor(detail?: string) {
+    super('bucket_not_found', 'Bucket does not exist', 404, detail);
+    this.name = 'BucketNotFoundError';
+    Object.setPrototypeOf(this, BucketNotFoundError.prototype);
+  }
+}
+
+export class CredentialLimitError extends MoogoError {
+  constructor(detail?: string) {
+    super('credential_limit', 'Too many storage credentials', 409, detail);
+    this.name = 'CredentialLimitError';
+    Object.setPrototypeOf(this, CredentialLimitError.prototype);
+  }
+}
+
+export class RateLimitedError extends MoogoError {
+  public readonly retryAfter: number;
+  public readonly resetAt: number | null;
+
+  constructor(retryAfter: number, resetAt: number | null, detail?: string) {
+    super('rate_limited', 'Too many requests', 429, detail);
+    this.name = 'RateLimitedError';
+    this.retryAfter = retryAfter;
+    this.resetAt = resetAt;
+    Object.setPrototypeOf(this, RateLimitedError.prototype);
+  }
+
+  static fromResponse(response: Response, data: any): RateLimitedError {
+    const retryAfter = parseInt(response.headers.get('Retry-After') || '1', 10);
+    const resetAt = response.headers.get('X-RateLimit-Reset')
+      ? parseInt(response.headers.get('X-RateLimit-Reset')!, 10)
+      : null;
+    return new RateLimitedError(retryAfter, resetAt, data?.error?.detail);
+  }
+}
+
+export class InvalidBodyError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_body', 'Malformed JSON or missing required fields', 400, detail);
+    this.name = 'InvalidBodyError';
+    Object.setPrototypeOf(this, InvalidBodyError.prototype);
+  }
+}
+
+export class InvalidExpiresInError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_expires_in', 'expires_in is outside the 60-604800 second range', 400, detail);
+    this.name = 'InvalidExpiresInError';
+    Object.setPrototypeOf(this, InvalidExpiresInError.prototype);
+  }
+}
+
+export class InvalidMethodError extends MoogoError {
+  constructor(detail?: string) {
+    super('invalid_method', 'A signed URL was requested with a method other than GET or PUT', 400, detail);
+    this.name = 'InvalidMethodError';
+    Object.setPrototypeOf(this, InvalidMethodError.prototype);
+  }
+}
+
+export class UnauthorizedError extends MoogoError {
+  constructor(detail?: string) {
+    super('unauthorized', 'Authentication required', 401, detail);
+    this.name = 'UnauthorizedError';
+    Object.setPrototypeOf(this, UnauthorizedError.prototype);
+  }
+}
+
+/** Map error codes to error classes */
+const errorMap: Record<string, new (detail?: string) => MoogoError> = {
+  missing_key: MissingKeyError,
+  invalid_key: InvalidKeyError,
+  key_too_long: KeyTooLongError,
+  key_taken: KeyTakenError,
+  invalid_bucket: InvalidBucketError,
+  invalid_cursor: InvalidCursorError,
+  invalid_order: InvalidOrderError,
+  body_too_large: BodyTooLargeError,
+  object_too_large: ObjectTooLargeError,
+  unsupported_media_type: UnsupportedMediaTypeError,
+  quota_exceeded: QuotaExceededError,
+  project_paused: ProjectPausedError,
+  link_expired: LinkExpiredError,
+  not_found: NotFoundError,
+  bucket_not_found: BucketNotFoundError,
+  credential_limit: CredentialLimitError,
+  invalid_body: InvalidBodyError,
+  invalid_expires_in: InvalidExpiresInError,
+  invalid_method: InvalidMethodError,
+  unauthorized: UnauthorizedError,
+};
+
+/**
+ * Create a typed error from an API response.
+ * Falls back to generic MoogoError for unknown codes.
+ */
+export function createErrorFromResponse(response: Response, data: any): MoogoError {
+  if (response.status === 429) {
+    return RateLimitedError.fromResponse(response, data);
+  }
+
+  const errorCode = data?.error?.code;
+  if (errorCode && errorMap[errorCode]) {
+    return new errorMap[errorCode](data.error.detail);
+  }
+
+  return MoogoError.fromResponse(response, data);
+}

package/src/index.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Basic type and structure tests for the Moogo client.
+ * These verify the exports and types compile correctly.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  MoogoClient,
+  createClientFromEnv,
+  MoogoError,
+  RateLimitedError,
+  NotFoundError,
+  createErrorFromResponse,
+} from './index.js';
+import type {
+  ClientConfig,
+  Bucket,
+  ObjectResponse,
+  ListObjectsQuery,
+  ListObjectsResponse,
+  StorageCredential,
+} from './types.js';
+
+describe('MoogoClient types', () => {
+  it('should accept valid config', () => {
+    const config: ClientConfig = {
+      baseUrl: 'https://api.moogo.dev',
+      projectId: 'test-project',
+      accessKeyId: 'test-key',
+      secretKey: 'test-secret',
+    };
+    expect(config.baseUrl).toBe('https://api.moogo.dev');
+  });
+
+  it('should have correct Bucket type', () => {
+    const bucket: Bucket = {
+      id: 'bucket-1',
+      name: 'test-bucket',
+      object_count: 0,
+      size_bytes: 0,
+      created_at: '2024-01-01T00:00:00Z',
+      is_public: false,
+      allowed_types: ['image/*'],
+      max_object_size_bytes: 1024 * 1024,
+      quota_bytes: 1024 * 1024 * 100,
+    };
+    expect(bucket.name).toBe('test-bucket');
+  });
+
+  it('should have correct ObjectResponse type', () => {
+    const obj: ObjectResponse = {
+      id: 'obj-1',
+      bucket_id: 'bucket-1',
+      bucket: 'test-bucket',
+      key: 'test.png',
+      size_bytes: 1024,
+      content_type: 'image/png',
+      is_public: true,
+      etag: '"abc123"',
+      url: 'https://api.moogo.dev/p/proj/bucket/test.png',
+      preview_url: '/api/projects/proj/bucket/test.png',
+      public_url: 'https://cdn.moogo.dev/pub/proj/test.png',
+      public_url_base: 'https://cdn.moogo.dev',
+      url_base: 'https://api.moogo.dev',
+      created_at: '2024-01-01T00:00:00Z',
+      updated_at: '2024-01-01T00:00:00Z',
+      last_modified: '2024-01-01T00:00:00Z',
+    };
+    expect(obj.public_url_base).toBe('https://cdn.moogo.dev');
+  });
+
+  it('should have correct ListObjectsQuery type', () => {
+    const query: ListObjectsQuery = {
+      bucket: 'my-bucket',
+      prefix: 'images/',
+      search: 'png',
+      order_by: 'created',
+      order_dir: 'desc',
+      limit: 50,
+      cursor: 'cursor123',
+    };
+    expect(query.order_by).toBe('created');
+  });
+
+  it('should have correct ListObjectsResponse type', () => {
+    const response: ListObjectsResponse = {
+      success: true,
+      objects: [],
+      next_cursor: null,
+      total: 0,
+    };
+    expect(response.success).toBe(true);
+  });
+});
+
+describe('MoogoClient instantiation', () => {
+  it('should create client with config', () => {
+    const client = new MoogoClient({
+      baseUrl: 'https://api.moogo.dev',
+      projectId: 'test-project',
+      accessKeyId: 'test-key',
+      secretKey: 'test-secret',
+    });
+    expect(client).toBeInstanceOf(MoogoClient);
+  });
+
+  it('should create client from env', () => {
+    const originalEnv = process.env;
+    process.env = {
+      ...originalEnv,
+      MOOGO_API_URL: 'https://api.moogo.dev',
+      MOOGO_PROJECT_ID: 'test-project',
+      MOOGO_BUCKET_ACCESS_KEY_ID: 'test-key',
+      MOOGO_BUCKET_SECRET_KEY: 'test-secret',
+    };
+    const client = createClientFromEnv();
+    expect(client).toBeInstanceOf(MoogoClient);
+    process.env = originalEnv;
+  });
+
+  it('should throw on missing required config', () => {
+    expect(() => new MoogoClient({
+      baseUrl: '',
+      projectId: 'test',
+      accessKeyId: 'test',
+      secretKey: 'test',
+    })).toThrow('baseUrl is required');
+
+    expect(() => new MoogoClient({
+      baseUrl: 'https://api.moogo.dev',
+      projectId: '',
+      accessKeyId: 'test',
+      secretKey: 'test',
+    })).toThrow('projectId is required');
+  });
+});
+
+describe('Error classes', () => {
+  it('should create MoogoError with correct properties', () => {
+    const error = new MoogoError('test_code', 'Test message', 400, 'detail');
+    expect(error.code).toBe('test_code');
+    expect(error.message).toBe('Test message');
+    expect(error.status).toBe(400);
+    expect(error.detail).toBe('detail');
+  });
+
+  it('should create RateLimitedError with retry info', () => {
+    const error = new RateLimitedError(60, 1234567890, 'Too many requests');
+    expect(error.retryAfter).toBe(60);
+    expect(error.resetAt).toBe(1234567890);
+    expect(error.status).toBe(429);
+  });
+
+  it('should create specific error types', () => {
+    const notFound = new NotFoundError('Object not found');
+    expect(notFound.code).toBe('not_found');
+    expect(notFound.status).toBe(404);
+  });
+});
+
+describe('createErrorFromResponse', () => {
+  const mockResponse = (status: number, headers: Record<string, string> = {}) => ({
+    status,
+    ok: status >= 200 && status < 300,
+    headers: {
+      get: (key: string) => headers[key.toLowerCase()] || null,
+    },
+  });
+
+  it('should create RateLimitedError for 429', () => {
+    const response = mockResponse(429, {
+      'retry-after': '60',
+      'x-ratelimit-reset': '1234567890',
+    });
+    const error = createErrorFromResponse(response as any, { error: { code: 'rate_limited', message: 'Too many', detail: 'detail' } });
+    expect(error).toBeInstanceOf(RateLimitedError);
+    expect(error.retryAfter).toBe(60);
+    expect(error.resetAt).toBe(1234567890);
+  });
+
+  it('should create NotFoundError for not_found code', () => {
+    const response = mockResponse(404);
+    const error = createErrorFromResponse(response as any, { error: { code: 'not_found', message: 'Not found', detail: 'detail' } });
+    expect(error).toBeInstanceOf(NotFoundError);
+  });
+
+  it('should fallback to generic MoogoError for unknown codes', () => {
+    const response = mockResponse(500);
+    const error = createErrorFromResponse(response as any, { error: { code: 'unknown_code', message: 'Unknown', detail: 'detail' } });
+    expect(error).toBeInstanceOf(MoogoError);
+    expect(error.code).toBe('unknown_code');
+  });
+});
+
+describe('Client method signatures', () => {
+  let client: MoogoClient;
+
+  beforeEach(() => {
+    client = new MoogoClient({
+      baseUrl: 'https://api.moogo.dev',
+      projectId: 'test-project',
+      accessKeyId: 'test-key',
+      secretKey: 'test-secret',
+    });
+  });
+
+  it('should have bucket methods', () => {
+    expect(typeof client.listBuckets).toBe('function');
+    expect(typeof client.getBucketInfo).toBe('function');
+    expect(typeof client.createBucket).toBe('function');
+    expect(typeof client.updateBucket).toBe('function');
+    expect(typeof client.deleteBucket).toBe('function');
+    expect(typeof client.setBucketPublic).toBe('function');
+  });
+
+  it('should have object methods', () => {
+    expect(typeof client.upload).toBe('function');
+    expect(typeof client.download).toBe('function');
+    expect(typeof client.downloadBlob).toBe('function');
+    expect(typeof client.downloadText).toBe('function');
+    expect(typeof client.downloadArrayBuffer).toBe('function');
+    expect(typeof client.headObject).toBe('function');
+    expect(typeof client.deleteObject).toBe('function');
+    expect(typeof client.listObjects).toBe('function');
+    expect(typeof client.getPresignedUrl).toBe('function');
+    expect(typeof client.createSignedUpload).toBe('function');
+    expect(typeof client.updateObject).toBe('function');
+  });
+
+  it('should have credential methods', () => {
+    expect(typeof client.listCredentials).toBe('function');
+    expect(typeof client.createCredential).toBe('function');
+    expect(typeof client.rotateCredential).toBe('function');
+    expect(typeof client.revokeCredential).toBe('function');
+  });
+
+  it('should have utility methods', () => {
+    expect(typeof client.getPublicUrl).toBe('function');
+    expect(typeof client.getAuthenticatedUrl).toBe('function');
+    expect(typeof client.objectExists).toBe('function');
+    expect(typeof client.getObjectSize).toBe('function');
+    expect(typeof client.getObjectETag).toBe('function');
+  });
+});
+
+describe('URL helpers', () => {
+  let client: MoogoClient;
+
+  beforeEach(() => {
+    client = new MoogoClient({
+      baseUrl: 'https://api.moogo.dev',
+      projectId: 'test-project',
+      accessKeyId: 'test-key',
+      secretKey: 'test-secret',
+    });
+  });
+
+  it('should generate public URL', () => {
+    const url = client.getPublicUrl('test.png');
+    expect(url).toBe('https://api.moogo.dev/pub/test-project/test.png');
+  });
+
+  it('should generate public URL with custom base', () => {
+    const url = client.getPublicUrl('test.png', 'https://cdn.example.com');
+    expect(url).toBe('https://cdn.example.com/pub/test-project/test.png');
+  });
+
+  it('should generate authenticated URL', () => {
+    const url = client.getAuthenticatedUrl('test.png');
+    expect(url).toBe('https://api.moogo.dev/p/test-project/test.png');
+  });
+
+  it('should handle special characters in key', () => {
+    const url = client.getPublicUrl('path/to/file.png');
+    expect(url).toBe('https://api.moogo.dev/pub/test-project/path%2Fto%2Ffile.png');
+  });
+});

package/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * @moogodev/client - Official JavaScript/TypeScript client for Moogo object storage
+ *
+ * @example
+ * ```typescript
+ * import { MoogoClient, createClientFromEnv } from '@moogodev/client';
+ *
+ * // From environment variables
+ * const client = createClientFromEnv();
+ *
+ * // Or with explicit config
+ * const client = new MoogoClient({
+ *   baseUrl: 'https://api.moogo.dev',
+ *   projectId: 'your-project-id',
+ *   accessKeyId: 'your-access-key-id',
+ *   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/' });
+ *
+ * // Download
+ * const blob = await client.downloadBlob('avatars/user.png');
+ * ```
+ */
+
+// Types
+export type {
+  ClientConfig,
+  ProjectId,
+  BucketId,
+  ObjectKey,
+  ApiError,
+  ApiErrorResponse,
+  ApiSuccessResponse,
+  ObjectBase,
+  ObjectResponse,
+  Bucket,
+  CreateBucketRequest,
+  UpdateBucketRequest,
+  BucketInfoResponse,
+  ListBucketsResponse,
+  UploadResponse,
+  ListObjectsQuery,
+  ListObjectsResponse,
+  PresignedUrlRequest,
+  PresignedUrlResponse,
+  SignedUploadResponse,
+  StorageCredential,
+  ListCredentialsResponse,
+  CreateCredentialRequest,
+  CreateCredentialResponse,
+  RotateCredentialResponse,
+  DeleteResponse,
+} from './types.js';
+
+// Errors
+export {
+  MoogoError,
+  MissingKeyError,
+  InvalidKeyError,
+  KeyTooLongError,
+  KeyTakenError,
+  InvalidBucketError,
+  InvalidCursorError,
+  InvalidOrderError,
+  BodyTooLargeError,
+  ObjectTooLargeError,
+  UnsupportedMediaTypeError,
+  QuotaExceededError,
+  ProjectPausedError,
+  LinkExpiredError,
+  NotFoundError,
+  BucketNotFoundError,
+  CredentialLimitError,
+  RateLimitedError,
+  InvalidBodyError,
+  InvalidExpiresInError,
+  InvalidMethodError,
+  UnauthorizedError,
+  createErrorFromResponse,
+} from './errors.js';
+
+// Client
+export { MoogoClient, createClientFromEnv } from './client.js';