@ponxa/potatobase-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PotatoBase Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# PotatoBase Client SDK
+
+Official JavaScript/TypeScript client for PotatoBase - The DynamoDB platform built on SST v3.
+
+## Installation
+
+```bash
+npm install @potatobase/client
+# or
+yarn add @potatobase/client
+# or
+pnpm add @potatobase/client
+```
+
+## Quick Start
+
+```typescript
+import { PotatoBaseClient } from '@potatobase/client';
+
+// Initialize the client
+const client = new PotatoBaseClient({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.potatobase.com',
+  projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
+  apiKey: process.env.NEXT_PUBLIC_API_KEY, // Optional, for frontend usage
+});
+
+// Access your tables
+const products = client.table('products');
+const orders = client.table('orders');
+
+// Create a record
+const product = await products.create({
+  name: 'Awesome Product',
+  price: 29.99,
+  category: 'electronics'
+});
+
+// Query records
+const electronics = await products.query({
+  category: 'electronics'
+});
+
+// Get a single record
+const product = await products.get('product-id');
+
+// Update a record
+await products.update('product-id', {
+  price: 24.99
+});
+
+// Delete a record
+await products.delete('product-id');
+```
+
+## Advanced Usage
+
+### Batch Operations
+
+```typescript
+// Batch get multiple records
+const products = await client.table('products').batchGet([
+  'product-1',
+  'product-2',
+  'product-3'
+]);
+
+// Query with filters
+const expensiveProducts = await client.table('products').query({
+  category: 'electronics',
+  minPrice: 100
+});
+```
+
+### Real-time Updates (Coming Soon)
+
+```typescript
+// Subscribe to real-time changes
+const unsubscribe = client.table('orders').subscribe(
+  { status: 'pending' },
+  (order) => {
+    console.log('Order updated:', order);
+  }
+);
+
+// Cleanup
+unsubscribe();
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type safety:
+
+```typescript
+interface Product {
+  productId: string;
+  name: string;
+  price: number;
+  category: string;
+}
+
+const products = client.table<Product>('products');
+
+// TypeScript will enforce the Product interface
+const product = await products.create({
+  name: 'Type-safe Product',
+  price: 49.99,
+  category: 'electronics'
+});
+```
+
+## Environment Variables
+
+Create a `.env.local` file in your project:
+
+```env
+NEXT_PUBLIC_API_URL=https://api.potatobase.com
+NEXT_PUBLIC_PROJECT_ID=your-project-id
+NEXT_PUBLIC_API_KEY=your-api-key
+```
+
+## API Reference
+
+### PotatoBaseClient
+
+The main client class for interacting with PotatoBase.
+
+#### Constructor Options
+
+- `apiUrl` (string): The PotatoBase API endpoint
+- `projectId` (string): Your project ID
+- `apiKey` (string, optional): API key for frontend authentication
+
+### Table Methods
+
+All table operations return promises and support async/await:
+
+- `create(data)`: Create a new record
+- `get(id)`: Get a record by ID
+- `update(id, data)`: Update a record
+- `delete(id)`: Delete a record
+- `query(params)`: Query records with filters
+- `batchGet(ids)`: Get multiple records by IDs
+- `list(options)`: List all records with pagination
+
+## Error Handling
+
+```typescript
+try {
+  const product = await products.get('non-existent-id');
+} catch (error) {
+  if (error.code === 'NOT_FOUND') {
+    console.log('Product not found');
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/potatobase/client/blob/main/CONTRIBUTING.md) for details.
+
+## License
+
+MIT © PotatoBase Team
+
+## Support
+
+- Documentation: [https://docs.potatobase.com](https://docs.potatobase.com)
+- GitHub Issues: [https://github.com/potatobase/client/issues](https://github.com/potatobase/client/issues)
+- Discord: [Join our community](https://discord.gg/potatobase)

package/dist/index.d.mts

@@ -0,0 +1,460 @@
+/**
+ * PotatoBase Client Types
+ *
+ * Public type definitions for the SDK
+ */
+/**
+ * Client configuration
+ */
+interface ClientConfig {
+    /** Project ID (from PotatoBase dashboard) */
+    projectId: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Optional: Custom API URL (defaults to production) */
+    apiUrl?: string;
+    /** Optional: Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Range condition for filtering by date or number fields
+ */
+interface RangeCondition {
+    /** Field name to filter on (e.g., 'createdAt', 'price') */
+    field: string;
+    /** Greater than or equal */
+    gte?: string | number;
+    /** Less than or equal */
+    lte?: string | number;
+    /** Greater than */
+    gt?: string | number;
+    /** Less than */
+    lt?: string | number;
+    /** Between two values (inclusive) */
+    between?: [string | number, string | number];
+}
+/**
+ * Query parameters for table queries
+ */
+interface QueryParams<TRecord = any> {
+    /** GSI index name (e.g., 'byCategory') */
+    index?: string;
+    /** Filter conditions */
+    where?: Partial<TRecord>;
+    /** Range condition for date/number filtering */
+    range?: RangeCondition;
+    /** Max number of results */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * Query result with pagination
+ */
+interface QueryResult<TRecord> {
+    /** Array of records */
+    data: TRecord[];
+    /** Pagination cursor (if more results available) */
+    cursor?: string;
+}
+/**
+ * Type generator result
+ */
+interface TypeGenerationResult {
+    /** Generated TypeScript types as string */
+    types: string;
+}
+/**
+ * Error response from API
+ */
+interface ApiError {
+    message: string;
+    code?: string;
+    details?: any;
+}
+
+/**
+ * TableClient
+ *
+ * Provides type-safe CRUD operations for a specific table.
+ * Each table in your database gets its own TableClient instance.
+ *
+ * Example:
+ * ```typescript
+ * const products = pb.table('products');
+ * const items = await products.query({ where: { category: 'clothing' } });
+ * ```
+ */
+declare class TableClient<TRecord extends {
+    id: string;
+} = any> {
+    private apiUrl;
+    private apiKey;
+    private projectId;
+    private tableName;
+    private debug;
+    constructor(apiUrl: string, apiKey: string, projectId: string, tableName: string, debug?: boolean);
+    private callAPI;
+    /**
+     * Query records from the table
+     *
+     * @param params - Query parameters (index, where, range, limit, cursor)
+     * @returns Query result with data and optional cursor
+     *
+     * @example
+     * ```typescript
+     * // Query by primary key
+     * const result = await products.query({ where: { id: 'prod-1' } });
+     *
+     * // Query by GSI
+     * const result = await products.query({
+     *   index: 'byCategory',
+     *   where: { category: 'clothing' },
+     *   limit: 10
+     * });
+     *
+     * // Query with date range
+     * const result = await products.query({
+     *   index: 'byCategory',
+     *   where: { category: 'clothing' },
+     *   range: {
+     *     field: 'createdAt',
+     *     gte: '2025-01-01',
+     *     lte: '2025-01-31'
+     *   }
+     * });
+     * ```
+     */
+    query(params?: QueryParams<TRecord>): Promise<TRecord[]>;
+    /**
+     * Get a single record by ID
+     *
+     * @param id - Record ID
+     * @returns Record or null if not found
+     *
+     * @example
+     * ```typescript
+     * const product = await products.get('prod-1');
+     * ```
+     */
+    get(id: string): Promise<TRecord | null>;
+    /**
+     * Insert a new record
+     *
+     * @param data - Record data (must include 'id' field)
+     * @returns Created record
+     *
+     * @example
+     * ```typescript
+     * const newProduct = await products.insert({
+     *   id: 'prod-1',
+     *   title: 'T-Shirt',
+     *   price: 29.99,
+     *   category: 'clothing'
+     * });
+     * ```
+     */
+    insert(data: TRecord): Promise<TRecord>;
+    /**
+     * Update an existing record
+     *
+     * @param id - Record ID
+     * @param data - Fields to update
+     * @returns Updated record
+     *
+     * @example
+     * ```typescript
+     * const updated = await products.update('prod-1', {
+     *   price: 24.99,
+     *   stock: 100
+     * });
+     * ```
+     */
+    update(id: string, data: Partial<Omit<TRecord, 'id'>>): Promise<TRecord>;
+    /**
+     * Delete a record
+     *
+     * @param id - Record ID
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * await products.delete('prod-1');
+     * ```
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Create a new record (alias for insert)
+     *
+     * @param data - Record data (must include 'id' field)
+     * @returns Created record
+     *
+     * @example
+     * ```typescript
+     * const newProduct = await products.create({
+     *   id: 'prod-1',
+     *   title: 'T-Shirt',
+     *   price: 29.99,
+     *   category: 'clothing'
+     * });
+     * ```
+     */
+    create(data: TRecord): Promise<TRecord>;
+    /**
+     * Alias for query() - chainable method
+     *
+     * @example
+     * ```typescript
+     * const items = await products.from().query({ limit: 10 });
+     * ```
+     */
+    from(): this;
+}
+
+/**
+ * Helper functions for date range queries
+ *
+ * These functions make it easier to construct range conditions
+ * for common date/time filtering scenarios.
+ */
+
+/**
+ * Get ISO date string for N days ago from now
+ *
+ * @param days - Number of days ago
+ * @returns ISO date string
+ *
+ * @example
+ * ```typescript
+ * daysAgo(7)  // "2025-01-21T10:30:00.000Z" (if today is Jan 28)
+ * daysAgo(30) // "2024-12-29T10:30:00.000Z"
+ * ```
+ */
+declare function daysAgo(days: number): string;
+/**
+ * Get ISO date string for N hours ago from now
+ *
+ * @param hours - Number of hours ago
+ * @returns ISO date string
+ */
+declare function hoursAgo(hours: number): string;
+/**
+ * Get ISO date string for N minutes ago from now
+ *
+ * @param minutes - Number of minutes ago
+ * @returns ISO date string
+ */
+declare function minutesAgo(minutes: number): string;
+/**
+ * Get range condition for last N days
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @param days - Number of days to go back
+ * @returns RangeCondition object
+ *
+ * @example
+ * ```typescript
+ * // Get orders from last 7 days
+ * await pb.table('orders').query({
+ *   index: 'byCustomer',
+ *   where: { customerId: 'customer-1' },
+ *   range: lastDays('createdAt', 7)
+ * });
+ * ```
+ */
+declare function lastDays(field: string, days: number): RangeCondition;
+/**
+ * Get range condition for date between two dates
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @param startDate - Start date (inclusive)
+ * @param endDate - End date (inclusive)
+ * @returns RangeCondition object
+ *
+ * @example
+ * ```typescript
+ * // Get orders from January 2025
+ * await pb.table('orders').query({
+ *   index: 'byCustomer',
+ *   where: { customerId: 'customer-1' },
+ *   range: between('createdAt', '2025-01-01', '2025-01-31')
+ * });
+ * ```
+ */
+declare function between(field: string, startDate: string, endDate: string): RangeCondition;
+/**
+ * Get range condition for dates since a specific date
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @param date - Start date (inclusive)
+ * @returns RangeCondition object
+ *
+ * @example
+ * ```typescript
+ * // Get all orders since Jan 1, 2025
+ * await pb.table('orders').query({
+ *   index: 'byStatus',
+ *   where: { status: 'delivered' },
+ *   range: since('createdAt', '2025-01-01')
+ * });
+ * ```
+ */
+declare function since(field: string, date: string): RangeCondition;
+/**
+ * Get range condition for dates until a specific date
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @param date - End date (inclusive)
+ * @returns RangeCondition object
+ *
+ * @example
+ * ```typescript
+ * // Get all orders until Dec 31, 2024
+ * await pb.table('orders').query({
+ *   index: 'byCustomer',
+ *   where: { customerId: 'customer-1' },
+ *   range: until('createdAt', '2024-12-31')
+ * });
+ * ```
+ */
+declare function until(field: string, date: string): RangeCondition;
+/**
+ * Get range condition for this month
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @returns RangeCondition object
+ *
+ * @example
+ * ```typescript
+ * // Get orders from this month
+ * await pb.table('orders').query({
+ *   index: 'byStatus',
+ *   where: { status: 'processing' },
+ *   range: thisMonth('createdAt')
+ * });
+ * ```
+ */
+declare function thisMonth(field: string): RangeCondition;
+/**
+ * Get range condition for this year
+ *
+ * @param field - Field name (e.g., 'publishedAt')
+ * @returns RangeCondition object
+ */
+declare function thisYear(field: string): RangeCondition;
+/**
+ * Get range condition for today
+ *
+ * @param field - Field name (e.g., 'createdAt')
+ * @returns RangeCondition object
+ */
+declare function today(field: string): RangeCondition;
+
+/**
+ * @potatobase/client
+ *
+ * Official JavaScript/TypeScript client for PotatoBase.
+ * Type-safe, easy-to-use SDK for querying your DynamoDB data.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@potatobase/client';
+ * import type { Database } from './types/database';
+ *
+ * const pb = createClient<Database>({
+ *   projectId: 'proj_abc123',
+ *   apiKey: 'pk_live_xyz...',
+ * });
+ *
+ * // Type-safe queries!
+ * const products = await pb.table('products').query({
+ *   index: 'byCategory',
+ *   where: { category: 'clothing' }
+ * });
+ * ```
+ */
+
+/**
+ * PotatoBaseClient
+ *
+ * Main client class for interacting with PotatoBase.
+ * Provides access to tables and utility methods.
+ */
+declare class PotatoBaseClient<TDatabase = any> {
+    private config;
+    private tableClients;
+    constructor(config: ClientConfig);
+    /**
+     * Access a table by name
+     *
+     * Returns a TableClient instance for performing CRUD operations.
+     * TableClient instances are cached for performance.
+     *
+     * @param tableName - Name of the table
+     * @returns TableClient for the specified table
+     *
+     * @example
+     * ```typescript
+     * const products = pb.table('products');
+     * const items = await products.query({ limit: 10 });
+     * ```
+     */
+    table<TTable extends keyof TDatabase>(tableName: TTable): TableClient<TDatabase[TTable] extends infer R ? R & {
+        id: string;
+    } : any>;
+    /**
+     * Generate TypeScript types for your project
+     *
+     * Fetches the current schema and generates TypeScript interface definitions.
+     * Save the result to a .d.ts file in your project.
+     *
+     * @returns Generated TypeScript types as string
+     *
+     * @example
+     * ```typescript
+     * const types = await pb.generateTypes();
+     * fs.writeFileSync('./types/database.d.ts', types);
+     * ```
+     */
+    generateTypes(): Promise<string>;
+    /**
+     * Get the project ID
+     */
+    getProjectId(): string;
+    /**
+     * Get the API URL
+     */
+    getApiUrl(): string;
+    /**
+     * Clear all cached table clients
+     *
+     * Useful for testing or when you want to force fresh clients.
+     */
+    clearCache(): void;
+    /**
+     * Enable/disable debug logging
+     */
+    setDebug(enabled: boolean): void;
+}
+/**
+ * Create a new PotatoBase client
+ *
+ * @param config - Client configuration
+ * @returns PotatoBaseClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@potatobase/client';
+ * import type { Database } from './types/database';
+ *
+ * const pb = createClient<Database>({
+ *   projectId: 'proj_abc123',
+ *   apiKey: 'pk_live_xyz...',
+ * });
+ * ```
+ */
+declare function createClient<TDatabase = any>(config: ClientConfig): PotatoBaseClient<TDatabase>;
+
+export { type ApiError, type ClientConfig, PotatoBaseClient, type QueryParams, type QueryResult, type RangeCondition, TableClient, type TypeGenerationResult, between, createClient, daysAgo, hoursAgo, lastDays, minutesAgo, since, thisMonth, thisYear, today, until };