runwork 0.2.0

package/bundled-types/core-entity-do.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Core Entity Durable Object - SQL Storage
+ * DO NOT MODIFY THIS FILE - You may break the entity functionality
+ *
+ * EntityDO is the per-app entity storage system backed by native SQLite.
+ * All entities of the same type share one DO instance, keyed by entity ID.
+ *
+ * Features:
+ * - SQL-backed document storage with versioning (CAS operations)
+ * - Server-side query, search, sort, count via json_extract()
+ * - Security: field name validation, LIKE escaping, input limits
+ * - Auto-migration from legacy KV storage
+ *
+ * NO SCHEDULING - Use SchedulerDO for scheduled jobs
+ */
+import { DurableObject } from 'cloudflare:workers';
+import type { Env } from './core-utils';
+export declare const SAFE_FIELD_NAME: RegExp;
+export declare function validateFieldName(field: string): string;
+export declare function escapeLikePattern(input: string): string;
+export declare const QUERY_LIMITS: {
+    MAX_SEARCH_LENGTH: number;
+    MAX_FILTER_COUNT: number;
+    MAX_SEARCH_FIELDS: number;
+    MAX_LIMIT: number;
+    MAX_DATA_SIZE: number;
+};
+interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    cursor?: string | null;
+    filters?: Record<string, unknown>;
+    search?: {
+        query: string;
+        fields: string[];
+    };
+    sort?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
+}
+interface QueryResult {
+    items: Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>;
+    total: number;
+    hasMore: boolean;
+    next: string | null;
+}
+/**
+ * Versioned document type for entity storage
+ */
+export type Doc<T> = {
+    v: number;
+    data: T;
+};
+/**
+ * EntityDO - Per-app entity storage with SQL queries
+ *
+ * This Durable Object provides:
+ * - Document storage with optimistic concurrency (CAS) via SQLite
+ * - Query with search, sort, filter, pagination via json_extract()
+ * - Count with optional filters
+ * - Security validation on all field names
+ */
+export declare class EntityDO extends DurableObject<Env> {
+    ctx: DurableObjectState;
+    env: Env;
+    private _tableReady;
+    private _migrationDone;
+    constructor(ctx: DurableObjectState, env: Env);
+    private ensureTable;
+    private migrateFromKV;
+    getDoc(key: string): {
+        v: number;
+        data: unknown;
+    } | null;
+    casPut(key: string, expectedV: number, data: unknown): {
+        ok: boolean;
+        v: number;
+    };
+    del(key: string): boolean;
+    has(key: string): boolean;
+    queryEntities(options?: QueryOptions): QueryResult;
+    countEntities(filters?: Record<string, unknown>): number;
+    bulkCreate(items: Array<{
+        key: string;
+        data: unknown;
+    }>): Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>;
+    bulkUpdate(updates: Array<{
+        key: string;
+        data: Record<string, unknown>;
+    }>): Array<{
+        key: string;
+        ok: boolean;
+        v: number;
+        data: unknown;
+    }>;
+    bulkDelete(keys: string[]): number;
+    exportAll(): Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>;
+    importAll(items: Array<{
+        key: string;
+        v: number;
+        data: unknown;
+    }>): {
+        imported: number;
+    };
+}
+export {};

package/bundled-types/core-events.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core Events
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides:
+ * - emitEvent(): Fire-and-forget event emission to the workspace event stream
+ * - flog(): Structured logging that outputs JSON to sandbox stdout
+ *
+ * Events appear in the workspace activity feed and channel views.
+ * When running outside a workspace (standalone mode), calls are silently skipped.
+ */
+export interface EmitEventParams {
+    type: string;
+    entityType?: string;
+    entityId?: string;
+    summary: string;
+    metadata?: Record<string, unknown>;
+}
+interface EventEnv {
+    WORKSPACE_API_URL?: string;
+    WORKSPACE_API_KEY?: string;
+    WORKSPACE_ID?: string;
+    APP_ID?: string;
+    APP_NAME?: string;
+    DEPLOYMENT_MODE?: 'preview' | 'production';
+    WorkspaceObject?: DurableObjectNamespace;
+}
+/**
+ * Any context that supports waitUntil - compatible with both
+ * ExecutionContext (Hono route handlers) and DurableObjectState (DOs).
+ */
+type WaitUntilContext = Pick<ExecutionContext, 'waitUntil'>;
+/**
+ * Convert an app name to a kebab-case channel name.
+ * "My Cool App" -> "my-cool-app"
+ */
+export declare function toChannelName(appName: string): string;
+/**
+ * Structured log entry for sandbox stdout.
+ * Outputs JSON with a consistent schema so the platform can parse and display
+ * these entries in the observability timeline.
+ */
+export declare function flog(level: 'info' | 'warn' | 'error', system: string, message: string, data?: Record<string, unknown>): void;
+/**
+ * Emit an event to the workspace unified event stream.
+ * Fire-and-forget: uses ctx.waitUntil so it doesn't block the response.
+ * Silently skips if workspace env vars are not configured (standalone mode).
+ *
+ * Automatically routes events to a channel derived from APP_NAME when available.
+ */
+export declare function emitEvent(ctx: WaitUntilContext, env: EventEnv, event: EmitEventParams): void;
+export {};

package/bundled-types/core-file-storage.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Core File Storage Utilities for R2
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides the FileStorageClient class for R2 bucket operations.
+ * Use the FileStorageClient to upload, download, delete, and list files.
+ * Presigned URLs are generated via the platform API (vibe-apps don't have R2 credentials).
+ */
+import { type Env } from './core-utils';
+import type { FileMetadata, UploadOptions, DownloadOptions, ListFilesOptions, ListFilesResult, PresignedUrlRequest, PresignedUrlResponse } from './shared/core-types';
+export type { FileMetadata, UploadOptions, DownloadOptions, ListFilesOptions, ListFilesResult, PresignedUrlRequest, PresignedUrlResponse, };
+/**
+ * FileStorageClient - Wrapper for R2 bucket operations
+ *
+ * Use this client to:
+ * - Upload files directly to R2 (for smaller files via worker)
+ * - Download files directly from R2
+ * - List and manage files in the bucket
+ * - Get presigned URLs for direct R2 access (via platform API)
+ *
+ * @example
+ * ```typescript
+ * const storage = createFileStorageClient(env);
+ *
+ * // Upload a file
+ * const metadata = await storage.upload(fileData, {
+ *     name: 'document.pdf',
+ *     contentType: 'application/pdf'
+ * });
+ *
+ * // Get presigned URL for large file download
+ * const { url } = await storage.getPresignedDownloadUrl('path/to/file.pdf');
+ *
+ * // List files
+ * const { files, cursor } = await storage.list({ prefix: 'uploads/' });
+ * ```
+ */
+export declare class FileStorageClient {
+    private env;
+    private readonly bucket;
+    private readonly platformBaseUrl;
+    private readonly workspaceApiKey;
+    private readonly appId;
+    constructor(env: Env);
+    private extractOrigin;
+    /**
+     * Check if file storage is configured (R2 bucket bound)
+     */
+    isConfigured(): boolean;
+    /**
+     * Check if presigned URL generation is available (platform API configured)
+     */
+    canGeneratePresignedUrls(): boolean;
+    /**
+     * Generate a unique key for file storage
+     */
+    private generateKey;
+    /**
+     * Upload a file to R2
+     * For smaller files that can be processed through the worker.
+     * For large files, use getPresignedUploadUrl() for direct R2 upload.
+     *
+     * @example
+     * ```typescript
+     * const metadata = await storage.upload(fileBuffer, {
+     *     name: 'report.pdf',
+     *     contentType: 'application/pdf',
+     *     customMetadata: { department: 'sales' }
+     * });
+     * console.log('Uploaded:', metadata.key);
+     * ```
+     */
+    upload(data: ReadableStream | ArrayBuffer | string | Blob, options?: UploadOptions): Promise<FileMetadata>;
+    /**
+     * Download a file from R2
+     * Returns the R2ObjectBody which includes the body stream and metadata.
+     *
+     * @example
+     * ```typescript
+     * const object = await storage.download('path/to/file.pdf');
+     * if (object) {
+     *     return new Response(object.body, {
+     *         headers: { 'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream' }
+     *     });
+     * }
+     * ```
+     */
+    download(key: string, options?: DownloadOptions): Promise<R2ObjectBody | null>;
+    /**
+     * Delete a file from R2
+     * Returns true if the file existed, false otherwise.
+     *
+     * @example
+     * ```typescript
+     * const deleted = await storage.delete('path/to/file.pdf');
+     * console.log(deleted ? 'File deleted' : 'File did not exist');
+     * ```
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete multiple files from R2
+     *
+     * @example
+     * ```typescript
+     * await storage.deleteMany(['file1.pdf', 'file2.pdf', 'file3.pdf']);
+     * ```
+     */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * List files in R2 with optional prefix and pagination
+     *
+     * @example
+     * ```typescript
+     * // List all files in uploads/ folder
+     * const { files, cursor, truncated } = await storage.list({
+     *     prefix: 'uploads/',
+     *     limit: 100
+     * });
+     *
+     * // Paginate through results
+     * if (truncated && cursor) {
+     *     const nextPage = await storage.list({ prefix: 'uploads/', cursor });
+     * }
+     * ```
+     */
+    list(options?: ListFilesOptions): Promise<ListFilesResult>;
+    /**
+     * Get file metadata without downloading the file content
+     *
+     * @example
+     * ```typescript
+     * const metadata = await storage.getMetadata('path/to/file.pdf');
+     * if (metadata) {
+     *     console.log(`File size: ${metadata.size} bytes`);
+     * }
+     * ```
+     */
+    getMetadata(key: string): Promise<FileMetadata | null>;
+    /**
+     * Check if a file exists in R2
+     *
+     * @example
+     * ```typescript
+     * if (await storage.exists('path/to/file.pdf')) {
+     *     console.log('File exists');
+     * }
+     * ```
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get a presigned URL for uploading a file directly to R2
+     * The URL is generated by the platform API (vibe-apps don't have R2 credentials).
+     * Use this for large file uploads to avoid worker memory/CPU limits.
+     *
+     * @example
+     * ```typescript
+     * const { url, expiresAt } = await storage.getPresignedUploadUrl('uploads/large-video.mp4', {
+     *     contentType: 'video/mp4',
+     *     expiresIn: 3600 // 1 hour
+     * });
+     *
+     * // Client can now PUT directly to this URL
+     * await fetch(url, { method: 'PUT', body: fileData });
+     * ```
+     */
+    getPresignedUploadUrl(key: string, options?: {
+        contentType?: string;
+        expiresIn?: number;
+    }): Promise<PresignedUrlResponse>;
+    /**
+     * Get a presigned URL for downloading a file directly from R2
+     * The URL is generated by the platform API (vibe-apps don't have R2 credentials).
+     * Use this for large file downloads to avoid worker memory/CPU limits.
+     *
+     * @example
+     * ```typescript
+     * const { url, expiresAt } = await storage.getPresignedDownloadUrl('path/to/large-file.zip');
+     *
+     * // Redirect user to presigned URL or return it to client
+     * return Response.redirect(url, 302);
+     * ```
+     */
+    getPresignedDownloadUrl(key: string, options?: {
+        expiresIn?: number;
+    }): Promise<PresignedUrlResponse>;
+}
+/**
+ * Create a FileStorageClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createFileStorageClient } from './core-file-storage';
+ *
+ * app.post('/api/files/upload', async (c) => {
+ *     const storage = createFileStorageClient(c.env);
+ *     const formData = await c.req.formData();
+ *     const file = formData.get('file') as File;
+ *
+ *     const metadata = await storage.upload(file.stream(), {
+ *         name: file.name,
+ *         contentType: file.type
+ *     });
+ *
+ *     return c.json({ success: true, data: metadata });
+ * });
+ * ```
+ */
+export declare function createFileStorageClient(env: Env): FileStorageClient;
+import type { Hono } from 'hono';
+/**
+ * Mount file storage routes on the Hono app
+ * Provides REST API for R2 bucket operations
+ */
+export declare function fileStorageRoutes(app: Hono<{
+    Bindings: Env;
+}>): void;

package/bundled-types/core-integration-entities.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Core Integration Entity Utilities
+ * DO NOT MODIFY THIS FILE - You may break the integration entity functionality
+ *
+ * This module provides the IntegrationEntity base class for entities that are backed
+ * by external integrations (HubSpot, GitHub, Salesforce, etc.) instead of local storage.
+ *
+ * IntegrationEntity implements the unified EntityClass interface with EntityContext.
+ * All CRUD operations take ctx as the first parameter, matching the Entity class pattern.
+ */
+import type { EntityContext, ListOptions, PaginatedResult, EntityClass } from './core-entities';
+import type { Env } from './core-utils';
+export interface OperationConfig {
+    /** API endpoint path (use :id for ID placeholder) */
+    endpoint: string;
+}
+export interface IntegrationEntityConfig {
+    /** Integration identifier: "hubspot", "github", "salesforce", etc. */
+    integrationId: string;
+    /** Nango provider config key: "hubspot", "github", etc. */
+    providerConfigKey: string;
+    operations: {
+        list?: OperationConfig;
+        get?: OperationConfig;
+        create?: OperationConfig;
+        update?: OperationConfig;
+        delete?: OperationConfig;
+    };
+}
+/**
+ * Extract the entity data type from an IntegrationEntity constructor.
+ * e.g., IntegrationEntityData<typeof ContactEntity> = HubSpotContact
+ */
+type IntegrationEntityData<T> = T extends abstract new (...args: unknown[]) => IntegrationEntity<infer D> ? D : never;
+/**
+ * Base constructor type for IntegrationEntity subclasses
+ */
+type IntegrationEntityCtor = abstract new (...args: unknown[]) => IntegrationEntity<{
+    id: string;
+}>;
+/**
+ * Constructor with required static properties.
+ * This ensures the calling class has entityName, config, etc.
+ */
+type IntegrationEntityCtorWithConfig<TCtor> = TCtor & {
+    entityName: string;
+    config: IntegrationEntityConfig;
+    schema?: Record<string, unknown>;
+    getConnectionId(env: Env | Record<string, unknown>): string | undefined;
+};
+/**
+ * IntegrationEntityClass type - for type checking integration entity classes
+ */
+export interface IntegrationEntityClass<T extends {
+    id: string;
+} = {
+    id: string;
+}> extends EntityClass<T> {
+    config: IntegrationEntityConfig;
+}
+/**
+ * IntegrationEntity - Base class for entities backed by external integrations
+ *
+ * Implements the unified EntityClass interface with EntityContext as first parameter.
+ * This makes IntegrationEntity and Entity have identical CRUD interfaces.
+ *
+ * Extend this class to define entities that proxy CRUD operations to external services
+ * like HubSpot, GitHub, Salesforce, etc. via the IntegrationClient.
+ *
+ * @example
+ * ```typescript
+ * import { IntegrationEntity, IntegrationEntityConfig } from './core-integration-entities';
+ *
+ * interface HubSpotContact {
+ *   id: string;
+ *   properties: { email: string; firstname: string; lastname: string };
+ * }
+ *
+ * export class ContactEntity extends IntegrationEntity<HubSpotContact> {
+ *   static readonly entityName = 'hubspot_contact';
+ *   static readonly config: IntegrationEntityConfig = {
+ *     integrationId: 'hubspot',
+ *     providerConfigKey: 'hubspot',
+ *     operations: {
+ *       list: { endpoint: '/crm/v3/objects/contacts' },
+ *       get: { endpoint: '/crm/v3/objects/contacts/:id' },
+ *       create: { endpoint: '/crm/v3/objects/contacts' },
+ *       update: { endpoint: '/crm/v3/objects/contacts/:id' },
+ *       delete: { endpoint: '/crm/v3/objects/contacts/:id' },
+ *     },
+ *   };
+ *   static readonly schema = { fields: ['id', 'email', 'firstname', 'lastname'] };
+ * }
+ *
+ * // Usage (same pattern as Entity):
+ * const ctx = { env, client };
+ * const contacts = await ContactEntity.list(ctx, { limit: 50 });
+ * // contacts is PaginatedResult<HubSpotContact> - properly typed!
+ * const contact = await ContactEntity.get(ctx, 'contact-123');
+ * // contact is HubSpotContact | null - properly typed!
+ * ```
+ */
+export declare abstract class IntegrationEntity<T extends {
+    id: string;
+}> {
+    static readonly entityName: string;
+    static readonly config: IntegrationEntityConfig;
+    static readonly schema?: Record<string, unknown>;
+    /**
+     * Get connection ID from env var if explicitly set.
+     * Returns undefined when not set -- the proxy resolves connections
+     * dynamically via workspaceId + provider, so this is optional.
+     */
+    static getConnectionId(env: Env | Record<string, unknown>): string | undefined;
+    /**
+     * Get the IntegrationClient from context
+     * Throws if client is not available
+     */
+    private static getClient;
+    /**
+     * List entities from the integration with optional filters
+     * Filters are passed through as query parameters to the external API
+     * Note: Entities needing POST-based filtering should override this method
+     */
+    static list<TCtor extends IntegrationEntityCtor>(this: IntegrationEntityCtorWithConfig<TCtor>, ctx: EntityContext, options?: ListOptions): Promise<PaginatedResult<IntegrationEntityData<TCtor>>>;
+    /**
+     * Get a single entity by ID from the integration
+     */
+    static get<TCtor extends IntegrationEntityCtor>(this: IntegrationEntityCtorWithConfig<TCtor>, ctx: EntityContext, id: string): Promise<IntegrationEntityData<TCtor> | null>;
+    /**
+     * Create a new entity in the integration
+     */
+    static create<TCtor extends IntegrationEntityCtor>(this: IntegrationEntityCtorWithConfig<TCtor>, ctx: EntityContext, data: Partial<IntegrationEntityData<TCtor>>): Promise<IntegrationEntityData<TCtor>>;
+    /**
+     * Update an entity in the integration
+     */
+    static update<TCtor extends IntegrationEntityCtor>(this: IntegrationEntityCtorWithConfig<TCtor>, ctx: EntityContext, id: string, data: Partial<IntegrationEntityData<TCtor>>): Promise<IntegrationEntityData<TCtor>>;
+    /**
+     * Delete an entity from the integration
+     */
+    static delete<TCtor extends IntegrationEntityCtor>(this: IntegrationEntityCtorWithConfig<TCtor>, ctx: EntityContext, id: string): Promise<void>;
+}
+/**
+ * Type guard to check if a class is an IntegrationEntity
+ */
+export declare function isIntegrationEntity(cls: unknown): cls is IntegrationEntityClass;
+export {};

package/bundled-types/core-integrations.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Core Integration Utilities
+ * DO NOT MODIFY THIS FILE - You may break the integration functionality
+ *
+ * This module provides utilities for making API calls to third-party services
+ * through the platform's multi-provider integration system.
+ *
+ * Supported providers:
+ * - Nango: Self-hosted OAuth for 200+ APIs
+ * - Pipedream: Managed OAuth clients for business apps
+ * - AyrShare: Social media (Instagram, TikTok, Facebook, Twitter, etc.)
+ *
+ * Provider routing is automatic - the code is provider-agnostic.
+ * Use the IntegrationClient class to interact with connected third-party services.
+ */
+import { type Env } from './core-utils';
+import type { NangoActionResponse, NangoProxyOptions } from './shared/core-types';
+export type { NangoActionResponse, NangoProxyOptions, };
+/**
+ * Integration requirement definition
+ * Used in integration-requirements.ts to declare which integrations your app needs
+ */
+export interface IntegrationRequirement {
+    /** Integration provider ID (e.g., 'github', 'slack', 'hubspot') */
+    integrationId: string;
+    /** Why this integration is needed */
+    reason: string;
+    /** Whether the app cannot function without this integration */
+    required: boolean;
+}
+/**
+ * IntegrationClient - Wrapper for making API calls through Nango proxy
+ *
+ * Nango handles OAuth authentication and proxies requests to external APIs.
+ *
+ * For structured data access, prefer IntegrationEntity classes from './core-integration-entities'.
+ *
+ * @example
+ * ```typescript
+ * const client = new IntegrationClient(env);
+ *
+ * // GET request to HubSpot API
+ * const contacts = await client.proxy<{ results: Contact[] }>({
+ *     method: 'GET',
+ *     endpoint: '/crm/v3/objects/contacts',
+ *     providerConfigKey: 'hubspot'
+ * });
+ *
+ * // POST request to create a GitHub issue
+ * const issue = await client.proxy({
+ *     method: 'POST',
+ *     endpoint: '/repos/owner/repo/issues',
+ *     providerConfigKey: 'github',
+ *     data: { title: 'New Issue', body: 'Issue description' }
+ * });
+ * ```
+ */
+export declare class IntegrationClient {
+    private env;
+    private readonly proxyUrl;
+    private readonly proxyToken;
+    constructor(env: Env);
+    /**
+     * Fire-and-forget event emission for integration activity.
+     * Does not require waitUntil context - errors are silently swallowed.
+     */
+    private fireEvent;
+    /**
+     * Check if integrations are configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Check if a specific integration has a connection configured.
+     * The proxy resolves connections dynamically, so this returns true
+     * when the proxy is configured even without explicit env vars.
+     */
+    hasConnection(provider: string): boolean;
+    /**
+     * Normalize integration ID to canonical form for env var lookup.
+     * MUST be identical to platform's normalizeIntegrationId() in provider-config.ts.
+     *
+     * Strips provider prefixes (pd_, nango_, ayrshare_), common suffixes (-demo, _v1),
+     * and removes all separators for consistent cross-provider matching.
+     *
+     * Examples:
+     * - "pd_sendgrid" -> "sendgrid"
+     * - "google-drive" -> "googledrive"
+     * - "pd_google_drive" -> "googledrive"
+     * - "hubspot-demo" -> "hubspot"
+     */
+    private normalizeIntegrationId;
+    private getWorkspaceIntegrationId;
+    private getLegacyConnectionId;
+    /**
+     * Make a request to external API via platform proxy.
+     * Uses platformFetch which routes through WorkspaceObject DO in production
+     * to avoid 522 timeouts from WfP workers.
+     */
+    private makeRequest;
+    /**
+     * Make a proxy request to an external API through the integration proxy.
+     * Use this for all API calls to connected third-party services.
+     * Supports multiple providers (Nango, Pipedream, AyrShare) - routing is automatic.
+     *
+     * @example
+     * ```typescript
+     * // GET request
+     * const result = await client.proxy<{ results: Contact[] }>({
+     *     method: 'GET',
+     *     endpoint: '/crm/v3/objects/contacts',
+     *     providerConfigKey: 'hubspot'
+     * });
+     *
+     * // POST request with data
+     * const result = await client.proxy({
+     *     method: 'POST',
+     *     endpoint: '/repos/owner/repo/issues',
+     *     providerConfigKey: 'github',
+     *     data: { title: 'Bug Report', body: 'Description' }
+     * });
+     * ```
+     */
+    proxy<T = unknown>(options: NangoProxyOptions): Promise<NangoActionResponse<T>>;
+}
+/**
+ * Create an integration client instance
+ *
+ * @example
+ * ```typescript
+ * import { createIntegrationClient } from './core-integrations';
+ *
+ * app.get('/api/hubspot/contacts', async (c) => {
+ *     const client = createIntegrationClient(c.env);
+ *     const result = await client.proxy<{ results: Contact[] }>({
+ *         method: 'GET',
+ *         endpoint: '/crm/v3/objects/contacts',
+ *         providerConfigKey: 'hubspot'
+ *     });
+ *     return c.json(result);
+ * });
+ * ```
+ */
+export declare function createIntegrationClient(env: Env): IntegrationClient;