@tapstack/db 1.0.7 → 3.0.0

package/src/adapters/nodejs.adapter.ts

@@ -0,0 +1,298 @@
+/**
+ * Tapstack API Adapter
+ * Implements IInstanceAdapter for the Tapstack API at api.tapstack.com
+ */
+
+import {
+  IInstanceAdapter,
+  AdapterConfig,
+  HttpMethod,
+  RequestOptions,
+  ApiResponse,
+  AdapterError,
+} from './types';
+
+/**
+ * Default Tapstack API URL
+ */
+export const DEFAULT_API_URL = 'https://api.tapstack.com';
+
+/**
+ * Configuration for the Tapstack API adapter
+ */
+export interface NodeJSAdapterConfig extends AdapterConfig {
+  /**
+   * Base URL of the Tapstack API
+   * @default 'https://api.tapstack.com'
+   */
+  baseUrl?: string;
+
+  /**
+   * API key for authentication (for programmatic access)
+   */
+  apiKey?: string;
+
+  /**
+   * Service token for service-to-service calls
+   */
+  serviceToken?: string;
+
+  /**
+   * User token for frontend calls (static)
+   */
+  userToken?: string;
+
+  /**
+   * Function to get dynamic user token (alternative to static userToken)
+   * Use this in frontend apps where the token may change
+   */
+  getUserToken?: () => Promise<string | null>;
+}
+
+export class NodeJSAdapter implements IInstanceAdapter {
+  private workspaceId: string | null;
+  private baseUrl: string;
+
+  constructor(private config: NodeJSAdapterConfig) {
+    this.workspaceId = config.workspaceId ?? null;
+    this.baseUrl = config.baseUrl ?? DEFAULT_API_URL;
+  }
+
+  /**
+   * Map SDK paths to REST API paths
+   * Converts paths like 'records/contacts' to '/api/v1/objects/contacts/records'
+   */
+  private mapPath(path: string): string {
+    // Already a full path
+    if (path.startsWith('/api/')) {
+      return path;
+    }
+
+    // Schema operations
+    if (path.startsWith('schema/objects')) {
+      return `/api/v1/objects${path.replace('schema/objects', '')}`;
+    }
+    if (path.startsWith('schema/fields/')) {
+      const parts = path.split('/');
+      const objectSlug = parts[2];
+      const rest = parts.slice(3).join('/');
+      return `/api/v1/objects/${objectSlug}/fields${rest ? `/${rest}` : ''}`;
+    }
+
+    // Record operations: records/{objectSlug}/... -> /api/v1/objects/{objectSlug}/records/...
+    if (path.startsWith('records/')) {
+      const parts = path.split('/');
+      const objectSlug = parts[1];
+      const rest = parts.slice(2).join('/');
+      return `/api/v1/objects/${objectSlug}/records${rest ? `/${rest}` : ''}`;
+    }
+
+    // File operations
+    if (path.startsWith('files')) {
+      return `/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Automation operations
+    if (path.startsWith('automations')) {
+      return `/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Conversation operations
+    if (path.startsWith('conversations')) {
+      return `/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // AI operations
+    if (path.startsWith('ai')) {
+      return `/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Organization operations
+    if (path.startsWith('organizations')) {
+      return `/api${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Workspace operations
+    if (path.startsWith('workspaces')) {
+      return `/api${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Activity operations
+    if (path.startsWith('activity')) {
+      return `/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    }
+
+    // Default: add /api prefix
+    return `/api/${path}`;
+  }
+
+  /**
+   * Make a request to the Tapstack API
+   */
+  async request<T>(
+    method: HttpMethod,
+    path: string,
+    options?: RequestOptions
+  ): Promise<T> {
+    // Build the URL - API uses /api/v1 prefix for data operations
+    const apiPath = this.mapPath(path);
+    let url = `${this.baseUrl}${apiPath}`;
+
+    // Add query parameters
+    if (options?.params) {
+      const params = new URLSearchParams(options.params);
+      if (this.workspaceId && !options.params.workspaceId) {
+        params.set('workspaceId', this.workspaceId);
+      }
+      url += `?${params.toString()}`;
+    } else if (this.workspaceId) {
+      url += `?workspaceId=${this.workspaceId}`;
+    }
+
+    // Build headers
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.config.defaultHeaders,
+      ...options?.headers,
+    };
+
+    // Add authentication
+    if (this.config.apiKey) {
+      headers['X-API-Key'] = this.config.apiKey;
+    }
+
+    if (this.config.serviceToken) {
+      headers['Authorization'] = `Bearer ${this.config.serviceToken}`;
+    } else if (this.config.userToken) {
+      headers['Authorization'] = `Bearer ${this.config.userToken}`;
+    } else if (this.config.getUserToken) {
+      const token = await this.config.getUserToken();
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+    }
+
+    // Add workspace header
+    if (this.workspaceId) {
+      headers['X-Workspace-Id'] = this.workspaceId;
+    }
+
+    // Make the request
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    // Handle authentication errors
+    if (response.status === 401) {
+      this.config.onAuthError?.();
+      throw new AdapterError('Unauthorized', 'UNAUTHORIZED', 401);
+    }
+
+    // Parse response
+    const data = (await response.json()) as ApiResponse<T>;
+
+    // Handle API errors
+    if (!data.success) {
+      throw new AdapterError(
+        data.error?.message || 'Request failed',
+        data.error?.code || 'UNKNOWN_ERROR',
+        response.status
+      );
+    }
+
+    return data.data as T;
+  }
+
+  /**
+   * Upload a file to the Tapstack API
+   */
+  async upload<T>(
+    path: string,
+    file: File | Blob,
+    metadata?: Record<string, string>
+  ): Promise<T> {
+    const apiPath = this.mapPath(path);
+    let url = `${this.baseUrl}${apiPath}`;
+
+    if (this.workspaceId) {
+      url += `?workspaceId=${this.workspaceId}`;
+    }
+
+    const headers: Record<string, string> = {
+      ...this.config.defaultHeaders,
+    };
+
+    if (this.config.apiKey) {
+      headers['X-API-Key'] = this.config.apiKey;
+    }
+
+    if (this.config.serviceToken) {
+      headers['Authorization'] = `Bearer ${this.config.serviceToken}`;
+    } else if (this.config.userToken) {
+      headers['Authorization'] = `Bearer ${this.config.userToken}`;
+    } else if (this.config.getUserToken) {
+      const token = await this.config.getUserToken();
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+    }
+
+    if (this.workspaceId) {
+      headers['X-Workspace-Id'] = this.workspaceId;
+    }
+
+    const formData = new FormData();
+    formData.append('file', file);
+
+    if (metadata) {
+      for (const [key, value] of Object.entries(metadata)) {
+        formData.append(key, value);
+      }
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: formData,
+    });
+
+    if (response.status === 401) {
+      this.config.onAuthError?.();
+      throw new AdapterError('Unauthorized', 'UNAUTHORIZED', 401);
+    }
+
+    const data = (await response.json()) as ApiResponse<T>;
+
+    if (!data.success) {
+      throw new AdapterError(
+        data.error?.message || 'Upload failed',
+        data.error?.code || 'UPLOAD_ERROR',
+        response.status
+      );
+    }
+
+    return data.data as T;
+  }
+
+  /**
+   * Set the workspace context
+   */
+  setWorkspaceId(workspaceId: string | null): void {
+    this.workspaceId = workspaceId;
+  }
+
+  /**
+   * Get the current workspace ID
+   */
+  getWorkspaceId(): string | null {
+    return this.workspaceId;
+  }
+}
+
+
+
+
+
+

package/src/adapters/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Instance Adapter Interface
+ * Defines the contract for backend adapters (Edge Functions, Node.js API, etc.)
+ */
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export interface RequestOptions {
+  body?: unknown;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Core adapter interface that all backend implementations must implement
+ */
+export interface IInstanceAdapter {
+  /**
+   * Make an HTTP request to the backend
+   */
+  request<T>(
+    method: HttpMethod,
+    path: string,
+    options?: RequestOptions
+  ): Promise<T>;
+
+  /**
+   * Upload a file to the backend
+   */
+  upload<T>(
+    path: string,
+    file: File | Blob,
+    metadata?: Record<string, string>
+  ): Promise<T>;
+
+  /**
+   * Set the workspace context for subsequent requests
+   */
+  setWorkspaceId(workspaceId: string | null): void;
+
+  /**
+   * Get the current workspace ID
+   */
+  getWorkspaceId(): string | null;
+}
+
+/**
+ * Base configuration shared by all adapters
+ */
+export interface AdapterConfig {
+  /**
+   * Workspace ID for scoping requests
+   */
+  workspaceId?: string;
+
+  /**
+   * Callback when authentication fails
+   */
+  onAuthError?: () => void;
+
+  /**
+   * Custom headers to include in all requests
+   */
+  defaultHeaders?: Record<string, string>;
+}
+
+/**
+ * Standard API response format from Instance API
+ */
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+/**
+ * Paginated response format
+ */
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+/**
+ * Error thrown by adapters
+ */
+export class AdapterError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode?: number
+  ) {
+    super(message);
+    this.name = 'AdapterError';
+  }
+}
+
+
+
+
+
+

package/src/index.ts

@@ -1,70 +1,158 @@
+/**
+ * @tapstack/db - Tapstack Database Client
+ *
+ * A client for interacting with the Tapstack API at api.tapstack.com.
+ * Provides typed access to objects, fields, records, and more.
+ */
+
+// Export all types
 export * from './types';
-export * from './modules/objects';
-export * from './modules/fields';
-export * from './modules/records';
 
-import { AxiosResponse } from 'axios';
-import { BaseClient, BaseClientConfig } from '@tapstack/core';
+// Export adapters
+export * from './adapters';
+
+// Export modules
+export * from './modules';
+
+// Import for client class
+import { IInstanceAdapter } from './adapters/types';
+import { NodeJSAdapter, NodeJSAdapterConfig } from './adapters/nodejs.adapter';
 import { ObjectModule } from './modules/objects';
 import { FieldModule } from './modules/fields';
 import { RecordModule } from './modules/records';
-import { CreateFieldPayload, CreateObjectPayload } from './types';
-
-export interface TapstackDBClientConfig extends BaseClientConfig {}
+import { OrganizationModule } from './modules/organizations';
+import { WorkspaceModule } from './modules/workspaces';
+import { FileModule } from './modules/files';
+import { AutomationModule } from './modules/automations';
+import { ConversationModule } from './modules/conversations';
 
-export class TapstackDBClient extends BaseClient {
+/**
+ * Main Tapstack Database Client
+ * Uses an adapter to communicate with the Tapstack API
+ */
+export class TapstackDBClient {
   readonly objects: ObjectModule;
   readonly fields: FieldModule;
   readonly records: RecordModule;
+  readonly organizations: OrganizationModule;
+  readonly workspaces: WorkspaceModule;
+  readonly files: FileModule;
+  readonly automations: AutomationModule;
+  readonly conversations: ConversationModule;
 
-  constructor(config: TapstackDBClientConfig) {
-    super(config);
-    this.objects = new ObjectModule(this.client);
-    this.fields = new FieldModule(this.client);
-    this.records = new RecordModule(this.client);
-  }
+  private adapter: IInstanceAdapter;
 
-  async getObject(slug: string): Promise<AxiosResponse<any>> {
-    return this.client.get(`/system/${slug}`);
+  constructor(adapter: IInstanceAdapter) {
+    this.adapter = adapter;
+    this.objects = new ObjectModule(adapter);
+    this.fields = new FieldModule(adapter);
+    this.records = new RecordModule(adapter);
+    this.organizations = new OrganizationModule(adapter);
+    this.workspaces = new WorkspaceModule(adapter);
+    this.files = new FileModule(adapter);
+    this.automations = new AutomationModule(adapter);
+    this.conversations = new ConversationModule(adapter);
   }
 
-  async getAllObjects(): Promise<AxiosResponse<any>> {
-    return this.client.get(`/system`);
+  /**
+   * Set the workspace context for all subsequent requests
+   */
+  setWorkspaceId(workspaceId: string | null): void {
+    this.adapter.setWorkspaceId(workspaceId);
   }
 
-  async createObject(data: CreateObjectPayload): Promise<AxiosResponse<any>> {
-    return this.client.post(`/system`, data);
+  /**
+   * Get the current workspace ID
+   */
+  getWorkspaceId(): string | null {
+    return this.adapter.getWorkspaceId();
   }
 
-  async updateObject(slug: string, data: Partial<CreateObjectPayload>): Promise<AxiosResponse<any>> {
-    return this.client.put(`/system/${slug}`, data);
+  /**
+   * Get the underlying adapter (for advanced use cases)
+   */
+  getAdapter(): IInstanceAdapter {
+    return this.adapter;
   }
+}
 
-  async deleteObject(slug: string): Promise<AxiosResponse<any>> {
-    return this.client.delete(`/system/${slug}`);
-  }
+/**
+ * Client configuration options
+ */
+export type TapstackClientConfig = NodeJSAdapterConfig;
 
-  async getFields(slug: string): Promise<AxiosResponse<any>> {
-    return this.client.get(`/system/${slug}/fields`);
-  }
+/**
+ * Create a Tapstack API client
+ *
+ * @example
+ * ```typescript
+ * // With API key authentication
+ * const client = createClient({
+ *   apiKey: 'your-api-key',
+ *   workspaceId: 'ws-123',
+ * });
+ *
+ * // With user token (for frontend apps)
+ * const client = createClient({
+ *   getUserToken: async () => accessToken,
+ *   workspaceId: 'ws-123',
+ * });
+ *
+ * // With custom base URL
+ * const client = createClient({
+ *   baseUrl: 'https://custom-api.example.com',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Usage
+ * const objects = await client.objects.list();
+ * const records = await client.records.list('contacts');
+ * ```
+ */
+export function createClient(config: TapstackClientConfig): TapstackDBClient {
+  const adapter = new NodeJSAdapter(config);
+  return new TapstackDBClient(adapter);
+}
 
-  async getField(slug: string, fieldID: string): Promise<AxiosResponse<any>> {
-    return this.client.get(`/system/${slug}/fields/${fieldID}`);
-  }
+/**
+ * Create a client with a custom adapter
+ * Use this for advanced scenarios or custom backends
+ *
+ * @example
+ * ```typescript
+ * class CustomAdapter implements IInstanceAdapter {
+ *   // ... implementation
+ * }
+ *
+ * const client = createCustomClient(new CustomAdapter());
+ * ```
+ */
+export function createCustomClient(adapter: IInstanceAdapter): TapstackDBClient {
+  return new TapstackDBClient(adapter);
+}
 
-  async createField(slug: string, data: CreateFieldPayload): Promise<AxiosResponse<any>> {
-    return this.client.post(`/system/${slug}/fields`, data);
-  }
+// ==================== Legacy Exports (for backwards compatibility) ====================
 
-  async updateField(slug: string, fieldID: string, data: Partial<CreateFieldPayload>): Promise<AxiosResponse<any>> {
-    return this.client.put(`/system/${slug}/fields/${fieldID}`, data);
-  }
+/**
+ * @deprecated Use createClient instead
+ */
+export const createNodeJSClient = createClient;
 
-  async deleteField(slug: string, fieldID: string): Promise<AxiosResponse<any>> {
-    return this.client.delete(`/system/${slug}/fields/${fieldID}`);
-  }
+/**
+ * @deprecated Use TapstackClientConfig instead
+ */
+export interface TapstackDBClientConfig {
+  baseURL: string;
+  apiKey: string;
+}
 
-  async query(slug: string, variables: any): Promise<AxiosResponse<any>> {
-    return this.client.post(`/${slug}`, variables);
-  }
+/**
+ * @deprecated Use createClient instead
+ */
+export function createLegacyClient(config: TapstackDBClientConfig): TapstackDBClient {
+  const adapter = new NodeJSAdapter({
+    baseUrl: config.baseURL.replace('/api', ''),
+    apiKey: config.apiKey,
+  });
+  return new TapstackDBClient(adapter);
 }