@stack0/sdk 0.2.0

package/README.md

@@ -0,0 +1,388 @@
+# Stack0 SDK
+
+Official TypeScript/JavaScript SDK for Stack0 services.
+
+## Installation
+
+```bash
+npm install @stack0/sdk
+# or
+yarn add @stack0/sdk
+# or
+pnpm add @stack0/sdk
+# or
+bun add @stack0/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Stack0 } from '@stack0/sdk';
+
+const stack0 = new Stack0({
+  apiKey: 'stack0_...',
+});
+
+// Send an email
+const email = await stack0.mail.send({
+  from: 'noreply@example.com',
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Hello World</h1>',
+});
+
+// Upload a file to CDN
+const asset = await stack0.cdn.upload({
+  projectSlug: 'my-project',
+  file: fileBuffer,
+  filename: 'image.jpg',
+  mimeType: 'image/jpeg',
+});
+
+console.log(asset.cdnUrl); // https://cdn.stack0.com/...
+```
+
+## Configuration
+
+```typescript
+import { Stack0 } from '@stack0/sdk';
+
+const stack0 = new Stack0({
+  apiKey: 'stack0_...', // Required: Your API key
+  baseUrl: 'https://api.stack0.com/v1', // Optional: Custom API endpoint
+});
+```
+
+## CDN API
+
+Upload, manage, and transform assets with the CDN API.
+
+### Upload File
+
+```typescript
+// Simple upload (handles presigned URL flow automatically)
+const asset = await stack0.cdn.upload({
+  projectSlug: 'my-project',
+  file: fileBuffer, // Blob, Buffer, or ArrayBuffer
+  filename: 'photo.jpg',
+  mimeType: 'image/jpeg',
+  folder: '/images/avatars', // Optional
+  metadata: { userId: 'user_123' }, // Optional
+});
+
+console.log(asset.id); // Asset ID
+console.log(asset.cdnUrl); // CDN URL
+console.log(asset.status); // 'ready', 'processing', etc.
+```
+
+### Manual Upload Flow
+
+For more control, use the presigned URL flow:
+
+```typescript
+// 1. Get presigned upload URL
+const { uploadUrl, assetId } = await stack0.cdn.getUploadUrl({
+  projectSlug: 'my-project',
+  filename: 'document.pdf',
+  mimeType: 'application/pdf',
+  size: file.size,
+});
+
+// 2. Upload directly to S3
+await fetch(uploadUrl, {
+  method: 'PUT',
+  body: file,
+  headers: { 'Content-Type': 'application/pdf' },
+});
+
+// 3. Confirm upload
+const asset = await stack0.cdn.confirmUpload(assetId);
+```
+
+### List Assets
+
+```typescript
+const { assets, total, hasMore } = await stack0.cdn.list({
+  projectSlug: 'my-project',
+  type: 'image', // Optional: 'image', 'video', 'audio', 'document', 'other'
+  folder: '/images', // Optional
+  status: 'ready', // Optional
+  search: 'avatar', // Optional: search in filename
+  tags: ['profile'], // Optional
+  sortBy: 'createdAt', // Optional: 'createdAt', 'filename', 'size', 'type'
+  sortOrder: 'desc', // Optional: 'asc', 'desc'
+  limit: 20, // Optional
+  offset: 0, // Optional
+});
+
+for (const asset of assets) {
+  console.log(asset.filename, asset.cdnUrl);
+}
+```
+
+### Get Asset
+
+```typescript
+const asset = await stack0.cdn.get('asset-id');
+
+console.log(asset.filename);
+console.log(asset.size);
+console.log(asset.mimeType);
+console.log(asset.width, asset.height); // For images/videos
+```
+
+### Update Asset
+
+```typescript
+const asset = await stack0.cdn.update({
+  id: 'asset-id',
+  filename: 'new-name.jpg', // Optional
+  folder: '/images/archived', // Optional
+  tags: ['nature', 'sunset'], // Optional
+  alt: 'A beautiful sunset', // Optional
+  metadata: { category: 'landscape' }, // Optional
+});
+```
+
+### Delete Assets
+
+```typescript
+// Delete single asset
+await stack0.cdn.delete('asset-id');
+
+// Delete multiple assets
+const { deletedCount } = await stack0.cdn.deleteMany([
+  'asset-1',
+  'asset-2',
+  'asset-3',
+]);
+```
+
+### Move Assets
+
+```typescript
+await stack0.cdn.move({
+  assetIds: ['asset-1', 'asset-2'],
+  folder: '/images/archive', // Use null for root folder
+});
+```
+
+### Image Transformations
+
+Get optimized and transformed image URLs:
+
+```typescript
+const { url } = await stack0.cdn.getTransformUrl({
+  assetId: 'asset-id',
+  options: {
+    width: 800,
+    height: 600,
+    fit: 'cover', // 'cover', 'contain', 'fill', 'inside', 'outside'
+    format: 'webp', // 'webp', 'jpeg', 'png', 'avif'
+    quality: 80,
+  },
+});
+
+// Use in <img> tag
+// <img src={url} alt="Optimized image" />
+```
+
+### Folders
+
+```typescript
+// Get folder tree
+const tree = await stack0.cdn.getFolderTree({
+  projectSlug: 'my-project',
+  maxDepth: 3,
+});
+
+// Create folder
+const folder = await stack0.cdn.createFolder({
+  projectSlug: 'my-project',
+  name: 'avatars',
+  parentId: 'parent-folder-id', // Optional
+});
+
+// Delete folder
+await stack0.cdn.deleteFolder('folder-id');
+await stack0.cdn.deleteFolder('folder-id', true); // Delete with contents
+```
+
+## Mail API
+
+The Mail API is compatible with the Resend API for easy migration.
+
+### Send Email
+
+```typescript
+// Simple email
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Welcome to Stack0!</p>',
+});
+
+// With multiple recipients
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: ['user1@example.com', 'user2@example.com'],
+  subject: 'Newsletter',
+  html: '<p>Monthly update</p>',
+});
+
+// With name and email
+await stack0.mail.send({
+  from: { name: 'Acme Inc', email: 'noreply@acme.com' },
+  to: { name: 'John Doe', email: 'john@example.com' },
+  subject: 'Important Update',
+  html: '<p>Your account has been updated</p>',
+});
+
+// With CC and BCC
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  cc: 'manager@example.com',
+  bcc: ['audit@example.com', 'compliance@example.com'],
+  subject: 'Team Update',
+  html: '<p>Quarterly results</p>',
+});
+
+// With plain text alternative
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<h1>Welcome!</h1><p>Thanks for joining</p>',
+  text: 'Welcome! Thanks for joining',
+});
+
+// With tags and metadata
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  subject: 'Order Confirmation',
+  html: '<p>Your order #12345 is confirmed</p>',
+  tags: ['transactional', 'order'],
+  metadata: {
+    orderId: '12345',
+    customerId: 'cus_abc123',
+  },
+});
+
+// With template
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  subject: 'Welcome {{name}}',
+  templateId: 'template-uuid',
+  templateVariables: {
+    name: 'John',
+    activationUrl: 'https://example.com/activate?token=...',
+  },
+});
+
+// With attachments
+await stack0.mail.send({
+  from: 'hello@example.com',
+  to: 'user@example.com',
+  subject: 'Invoice',
+  html: '<p>Your invoice is attached</p>',
+  attachments: [
+    {
+      filename: 'invoice.pdf',
+      content: 'base64-encoded-content',
+      contentType: 'application/pdf',
+    },
+  ],
+});
+```
+
+### Get Email
+
+Retrieve details about a sent email:
+
+```typescript
+const email = await stack0.mail.get('email-id-uuid');
+
+console.log(email.status); // 'sent', 'delivered', 'bounced', etc.
+console.log(email.openedAt); // Date or null
+console.log(email.deliveredAt); // Date or null
+```
+
+## Error Handling
+
+```typescript
+try {
+  await stack0.mail.send({
+    from: 'hello@example.com',
+    to: 'user@example.com',
+    subject: 'Test',
+    html: '<p>Test</p>',
+  });
+} catch (error) {
+  if (error.statusCode === 401) {
+    console.error('Invalid API key');
+  } else if (error.statusCode === 403) {
+    console.error('Insufficient permissions');
+  } else if (error.statusCode === 400) {
+    console.error('Validation error:', error.message);
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import type {
+  // Mail types
+  SendEmailRequest,
+  SendEmailResponse,
+  // CDN types
+  Asset,
+  UploadUrlRequest,
+  ListAssetsRequest,
+  TransformOptions,
+} from '@stack0/sdk';
+```
+
+## Environment Variables
+
+For security, store your API key in environment variables:
+
+```typescript
+const stack0 = new Stack0({
+  apiKey: process.env.STACK0_API_KEY!,
+});
+```
+
+## Migration from Resend
+
+Stack0 Mail API is designed to be compatible with Resend:
+
+```typescript
+// Before (Resend)
+import { Resend } from 'resend';
+const resend = new Resend('re_...');
+await resend.emails.send({ ... });
+
+// After (Stack0)
+import { Stack0 } from '@stack0/sdk';
+const stack0 = new Stack0({ apiKey: 'stack0_...' });
+await stack0.mail.send({ ... });
+```
+
+## Support
+
+- Documentation: https://docs.stack0.com
+- Issues: https://github.com/CampbellVentures/stack0/issues
+- Email: support@stack0.com
+
+## License
+
+MIT

package/dist/cdn/index.d.mts

@@ -0,0 +1,322 @@
+import { H as HttpClientConfig } from '../http-client-Wr9lXo9_.mjs';
+
+/**
+ * Type definitions for Stack0 CDN API
+ */
+type AssetStatus = "pending" | "processing" | "ready" | "failed" | "deleted";
+type AssetType = "image" | "video" | "audio" | "document" | "other";
+interface Asset {
+    id: string;
+    filename: string;
+    originalFilename: string;
+    mimeType: string;
+    size: number;
+    type: AssetType;
+    s3Key: string;
+    cdnUrl: string;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    status: AssetStatus;
+    folder: string | null;
+    tags: string[] | null;
+    metadata: Record<string, unknown> | null;
+    alt: string | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+}
+interface UploadUrlRequest {
+    projectSlug: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    folder?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UploadUrlResponse {
+    uploadUrl: string;
+    assetId: string;
+    cdnUrl: string;
+    expiresAt: Date;
+}
+interface ConfirmUploadRequest {
+    assetId: string;
+}
+interface ConfirmUploadResponse {
+    asset: Asset;
+}
+interface GetAssetRequest {
+    id: string;
+}
+interface UpdateAssetRequest {
+    id: string;
+    filename?: string;
+    folder?: string;
+    tags?: string[];
+    alt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface DeleteAssetRequest {
+    id: string;
+}
+interface DeleteAssetsRequest {
+    ids: string[];
+}
+interface DeleteAssetsResponse {
+    success: boolean;
+    deletedCount: number;
+}
+interface ListAssetsRequest {
+    projectSlug: string;
+    folder?: string | null;
+    type?: AssetType;
+    status?: AssetStatus;
+    search?: string;
+    tags?: string[];
+    sortBy?: "createdAt" | "filename" | "size" | "type";
+    sortOrder?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}
+interface ListAssetsResponse {
+    assets: Asset[];
+    total: number;
+    hasMore: boolean;
+}
+interface MoveAssetsRequest {
+    assetIds: string[];
+    folder: string | null;
+}
+interface MoveAssetsResponse {
+    success: boolean;
+    movedCount: number;
+}
+interface TransformOptions {
+    width?: number;
+    height?: number;
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    format?: "webp" | "jpeg" | "png" | "avif";
+    quality?: number;
+}
+interface GetTransformUrlRequest {
+    assetId: string;
+    options: TransformOptions;
+}
+interface GetTransformUrlResponse {
+    url: string;
+    originalUrl: string;
+    width?: number;
+    height?: number;
+    format?: string;
+}
+interface FolderTreeNode {
+    id: string;
+    name: string;
+    path: string;
+    assetCount: number;
+    children: FolderTreeNode[];
+}
+interface GetFolderTreeRequest {
+    projectSlug: string;
+    maxDepth?: number;
+}
+interface CreateFolderRequest {
+    projectSlug: string;
+    name: string;
+    parentId?: string;
+}
+interface Folder {
+    id: string;
+    name: string;
+    path: string;
+    parentId: string | null;
+    assetCount: number;
+    totalSize: number;
+    createdAt: Date;
+    updatedAt: Date | null;
+}
+
+/**
+ * Stack0 CDN Client
+ * Upload, manage, and transform assets
+ */
+
+declare class CDN {
+    private http;
+    constructor(config: HttpClientConfig);
+    /**
+     * Generate a presigned URL for uploading a file
+     *
+     * @example
+     * ```typescript
+     * const { uploadUrl, assetId } = await cdn.getUploadUrl({
+     *   projectSlug: 'my-project',
+     *   filename: 'image.jpg',
+     *   mimeType: 'image/jpeg',
+     *   size: 1024 * 1024,
+     * });
+     *
+     * // Upload file to the presigned URL
+     * await fetch(uploadUrl, {
+     *   method: 'PUT',
+     *   body: file,
+     *   headers: { 'Content-Type': 'image/jpeg' },
+     * });
+     *
+     * // Confirm the upload
+     * const asset = await cdn.confirmUpload(assetId);
+     * ```
+     */
+    getUploadUrl(request: UploadUrlRequest): Promise<UploadUrlResponse>;
+    /**
+     * Confirm that an upload has completed
+     */
+    confirmUpload(assetId: string): Promise<Asset>;
+    /**
+     * Upload a file directly (handles presigned URL flow automatically)
+     *
+     * @example
+     * ```typescript
+     * const asset = await cdn.upload({
+     *   projectSlug: 'my-project',
+     *   file: fileBuffer,
+     *   filename: 'image.jpg',
+     *   mimeType: 'image/jpeg',
+     * });
+     * ```
+     */
+    upload(options: {
+        projectSlug: string;
+        file: Blob | Buffer | ArrayBuffer;
+        filename: string;
+        mimeType: string;
+        folder?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Asset>;
+    /**
+     * Get an asset by ID
+     *
+     * @example
+     * ```typescript
+     * const asset = await cdn.get('asset-id');
+     * console.log(asset.cdnUrl);
+     * ```
+     */
+    get(id: string): Promise<Asset>;
+    /**
+     * Update asset metadata
+     *
+     * @example
+     * ```typescript
+     * const asset = await cdn.update({
+     *   id: 'asset-id',
+     *   alt: 'A beautiful sunset',
+     *   tags: ['nature', 'sunset'],
+     * });
+     * ```
+     */
+    update(request: UpdateAssetRequest): Promise<Asset>;
+    /**
+     * Delete an asset
+     *
+     * @example
+     * ```typescript
+     * await cdn.delete('asset-id');
+     * ```
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Delete multiple assets
+     *
+     * @example
+     * ```typescript
+     * const result = await cdn.deleteMany(['asset-1', 'asset-2']);
+     * console.log(`Deleted ${result.deletedCount} assets`);
+     * ```
+     */
+    deleteMany(ids: string[]): Promise<DeleteAssetsResponse>;
+    /**
+     * List assets with filters and pagination
+     *
+     * @example
+     * ```typescript
+     * const { assets, total, hasMore } = await cdn.list({
+     *   projectSlug: 'my-project',
+     *   type: 'image',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    list(request: ListAssetsRequest): Promise<ListAssetsResponse>;
+    /**
+     * Move assets to a different folder
+     *
+     * @example
+     * ```typescript
+     * await cdn.move({
+     *   assetIds: ['asset-1', 'asset-2'],
+     *   folder: '/images/archive',
+     * });
+     * ```
+     */
+    move(request: MoveAssetsRequest): Promise<MoveAssetsResponse>;
+    /**
+     * Get a transformed image URL
+     *
+     * @example
+     * ```typescript
+     * const { url } = await cdn.getTransformUrl({
+     *   assetId: 'asset-id',
+     *   options: {
+     *     width: 800,
+     *     height: 600,
+     *     fit: 'cover',
+     *     format: 'webp',
+     *     quality: 80,
+     *   },
+     * });
+     * ```
+     */
+    getTransformUrl(request: GetTransformUrlRequest): Promise<GetTransformUrlResponse>;
+    /**
+     * Get folder tree for navigation
+     *
+     * @example
+     * ```typescript
+     * const tree = await cdn.getFolderTree({
+     *   projectSlug: 'my-project',
+     *   maxDepth: 3,
+     * });
+     * ```
+     */
+    getFolderTree(request: GetFolderTreeRequest): Promise<FolderTreeNode[]>;
+    /**
+     * Create a new folder
+     *
+     * @example
+     * ```typescript
+     * const folder = await cdn.createFolder({
+     *   projectSlug: 'my-project',
+     *   name: 'images',
+     * });
+     * ```
+     */
+    createFolder(request: CreateFolderRequest): Promise<Folder>;
+    /**
+     * Delete a folder
+     *
+     * @example
+     * ```typescript
+     * await cdn.deleteFolder('folder-id');
+     * ```
+     */
+    deleteFolder(id: string, deleteContents?: boolean): Promise<{
+        success: boolean;
+    }>;
+    private convertAssetDates;
+    private convertFolderDates;
+}
+
+export { type Asset, type AssetStatus, type AssetType, CDN, type ConfirmUploadRequest, type ConfirmUploadResponse, type CreateFolderRequest, type DeleteAssetRequest, type DeleteAssetsRequest, type DeleteAssetsResponse, type Folder, type FolderTreeNode, type GetAssetRequest, type GetFolderTreeRequest, type GetTransformUrlRequest, type GetTransformUrlResponse, type ListAssetsRequest, type ListAssetsResponse, type MoveAssetsRequest, type MoveAssetsResponse, type TransformOptions, type UpdateAssetRequest, type UploadUrlRequest, type UploadUrlResponse };