@ponxa/potatobase-client 0.1.0

package/dist/index.d.ts

@@ -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 };