@palbase/backend 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,381 @@
+import { E as EndpointContext, D as DBClient, L as Logger, C as CacheClient, P as PalbaseBindings } from './endpoint-tZi55HU8.cjs';
+export { A as AuthConfig, a as EndpointConfig, H as HttpMethod, M as Middleware, b as MiddlewareContext, c as MiddlewareHandler, R as RateLimitConfig, U as User, d as defineEndpoint, e as defineMiddleware } from './endpoint-tZi55HU8.cjs';
+export { z } from 'zod';
+
+/** HTTP error with structured error response format. */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly errorDescription: string;
+    constructor(status: number, error: string, errorDescription: string);
+    /**
+     * Serialize to the standard Palbase error response format.
+     * The `requestId` is injected by the runtime layer from the request context.
+     * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+     */
+    toJSON(requestId?: string): {
+        error: string;
+        error_description: string;
+        status: number;
+        request_id?: string;
+    };
+}
+
+/** Backoff strategy for worker retries. */
+type BackoffStrategy = "exponential" | "linear" | "fixed";
+/** Configuration for a background worker. */
+interface WorkerConfig<TPayload = unknown> {
+    /** Worker name — must be unique across the project. */
+    name: string;
+    /** Maximum number of retries before sending to dead letter queue. Defaults to 3. */
+    retry?: number;
+    /** Execution timeout in seconds. Defaults to 30. */
+    timeout?: number;
+    /** Backoff strategy between retries. Defaults to "exponential". */
+    backoff?: BackoffStrategy;
+    /** Handler function that processes the job payload. */
+    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers">, payload: TPayload) => Promise<void>;
+}
+/** Resolved worker configuration with defaults applied. */
+interface ResolvedWorkerConfig<TPayload = unknown> {
+    name: string;
+    retry: number;
+    timeout: number;
+    backoff: BackoffStrategy;
+    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers">, payload: TPayload) => Promise<void>;
+}
+/**
+ * Define a background worker that processes jobs from the queue.
+ *
+ * Workers are placed in the `workers/` directory and auto-discovered at deploy time.
+ *
+ * @example
+ * ```ts
+ * export default defineWorker({
+ *   name: "send-email",
+ *   retry: 5,
+ *   timeout: 60,
+ *   backoff: "exponential",
+ *   handler: async (ctx, payload: { to: string; subject: string }) => {
+ *     await sendEmail(payload.to, payload.subject);
+ *   },
+ * });
+ * ```
+ */
+declare function defineWorker<TPayload = unknown>(config: WorkerConfig<TPayload>): ResolvedWorkerConfig<TPayload>;
+
+/** Context injected into job handlers — subset of EndpointContext without request-specific fields. */
+interface JobContext {
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    queue: {
+        enqueue(workerName: string, payload: unknown): Promise<string>;
+    };
+    palbase: PalbaseBindings;
+    projectId: string;
+    environmentId: string;
+}
+/** Configuration for defining a scheduled job. */
+interface JobConfig {
+    /** Unique job name — alphanumeric, underscore, hyphen only. */
+    name: string;
+    /** Cron expression (e.g., "0 3 * * *"). */
+    schedule: string;
+    /** Execution timeout in seconds. Defaults to 30. */
+    timeout?: number;
+    /** Job handler function. */
+    handler: (ctx: JobContext) => Promise<void>;
+}
+/** Resolved job configuration with defaults applied. */
+interface ResolvedJobConfig {
+    name: string;
+    schedule: string;
+    timeout: number;
+    handler: (ctx: JobContext) => Promise<void>;
+}
+/**
+ * Define a scheduled cron job.
+ *
+ * Jobs are placed in the `jobs/` directory and auto-discovered at deploy time.
+ *
+ * @example
+ * ```ts
+ * export default defineJob({
+ *   name: "cleanup-expired",
+ *   schedule: "0 3 * * *", // every day at 3 AM
+ *   timeout: 60,
+ *   handler: async (ctx) => {
+ *     await ctx.db.delete("sessions", "expired < NOW()");
+ *     ctx.log.info("Cleaned up expired sessions");
+ *   },
+ * });
+ * ```
+ */
+declare function defineJob(config: JobConfig): ResolvedJobConfig;
+
+/** Supported webhook provider types. */
+type WebhookProvider = "stripe" | "github" | "twilio" | "sendgrid" | "slack" | "discord" | "livekit";
+/** Context injected into webhook handlers — no user (webhooks are machine-to-machine). */
+interface WebhookContext {
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    queue: {
+        enqueue(workerName: string, payload: unknown): Promise<string>;
+    };
+    palbase: PalbaseBindings;
+    projectId: string;
+    environmentId: string;
+    requestId: string;
+}
+/** Secret reference — resolves from environment variables at runtime. */
+interface EnvSecretRef {
+    env: string;
+}
+/** Provider-specific event maps for type-safe event handlers. */
+interface ProviderEventMap {
+    stripe: {
+        "checkout.session.completed": Record<string, unknown>;
+        "payment_intent.succeeded": Record<string, unknown>;
+        "payment_intent.payment_failed": Record<string, unknown>;
+        "customer.subscription.created": Record<string, unknown>;
+        "customer.subscription.updated": Record<string, unknown>;
+        "customer.subscription.deleted": Record<string, unknown>;
+        "invoice.paid": Record<string, unknown>;
+        "invoice.payment_failed": Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    github: {
+        push: Record<string, unknown>;
+        pull_request: Record<string, unknown>;
+        issues: Record<string, unknown>;
+        "pull_request.opened": Record<string, unknown>;
+        "pull_request.closed": Record<string, unknown>;
+        "pull_request.merged": Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    twilio: {
+        "message.received": Record<string, unknown>;
+        "message.sent": Record<string, unknown>;
+        "call.completed": Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    sendgrid: {
+        delivered: Record<string, unknown>;
+        bounce: Record<string, unknown>;
+        open: Record<string, unknown>;
+        click: Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    slack: {
+        url_verification: Record<string, unknown>;
+        event_callback: Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    discord: {
+        PING: Record<string, unknown>;
+        MESSAGE_CREATE: Record<string, unknown>;
+        INTERACTION_CREATE: Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+    livekit: {
+        "room.started": Record<string, unknown>;
+        "room.finished": Record<string, unknown>;
+        "participant.joined": Record<string, unknown>;
+        "participant.left": Record<string, unknown>;
+        [key: string]: Record<string, unknown>;
+    };
+}
+/** Event handler function type. */
+type WebhookEventHandler<TEvent = Record<string, unknown>> = (ctx: WebhookContext, event: TEvent) => Promise<void>;
+/** Provider-based webhook configuration. */
+interface ProviderWebhookConfig<P extends WebhookProvider = WebhookProvider> {
+    provider: P;
+    secret: EnvSecretRef;
+    events: {
+        [K in keyof ProviderEventMap[P]]?: WebhookEventHandler<ProviderEventMap[P][K]>;
+    };
+}
+/** Incoming request representation for custom verify functions. */
+interface WebhookRequest {
+    headers: Record<string, string>;
+    body: string;
+    method: string;
+    url: string;
+}
+/** Custom webhook configuration. */
+interface CustomWebhookConfig {
+    path: string;
+    verify?: (req: WebhookRequest) => Promise<boolean> | boolean;
+    handler: (ctx: WebhookContext, payload: Record<string, unknown>) => Promise<void>;
+}
+/** Resolved provider webhook (internal). */
+interface ResolvedProviderWebhook<P extends WebhookProvider = WebhookProvider> {
+    type: "provider";
+    provider: P;
+    secret: EnvSecretRef;
+    events: Record<string, WebhookEventHandler>;
+}
+/** Resolved custom webhook (internal). */
+interface ResolvedCustomWebhook {
+    type: "custom";
+    path: string;
+    verify?: (req: WebhookRequest) => Promise<boolean> | boolean;
+    handler: (ctx: WebhookContext, payload: Record<string, unknown>) => Promise<void>;
+}
+/** Union of resolved webhook types. */
+type ResolvedWebhookConfig = ResolvedProviderWebhook | ResolvedCustomWebhook;
+/**
+ * Define a provider-based webhook.
+ *
+ * @example
+ * ```ts
+ * export default defineWebhook({
+ *   provider: "stripe",
+ *   secret: { env: "STRIPE_WEBHOOK_SECRET" },
+ *   events: {
+ *     "checkout.session.completed": async (ctx, event) => {
+ *       await ctx.db.insert("orders", { status: "paid" });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineWebhook<P extends WebhookProvider>(config: ProviderWebhookConfig<P>): ResolvedProviderWebhook<P>;
+/**
+ * Define a custom webhook with optional verification.
+ *
+ * @example
+ * ```ts
+ * export default defineWebhook({
+ *   path: "/webhooks/livekit",
+ *   verify: async (req) => req.headers["x-api-key"] === "secret",
+ *   handler: async (ctx, payload) => {
+ *     ctx.log.info("Received webhook", payload);
+ *   },
+ * });
+ * ```
+ */
+declare function defineWebhook(config: CustomWebhookConfig): ResolvedCustomWebhook;
+
+/** Context injected into hook handlers. */
+interface HookContext {
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    queue: {
+        enqueue(workerName: string, payload: unknown): Promise<string>;
+    };
+    palbase: PalbaseBindings;
+    projectId: string;
+    environmentId: string;
+}
+/** Payload for auth.onUserCreated hook. */
+interface UserCreatedEvent {
+    user: {
+        id: string;
+        email: string;
+        role: string;
+        metadata: Record<string, unknown>;
+        createdAt: string;
+    };
+}
+/** Payload for auth.onSignIn hook. */
+interface SignInEvent {
+    user: {
+        id: string;
+        email: string;
+        role: string;
+    };
+    provider: string;
+    timestamp: string;
+}
+/** Payload for auth.onSignOut hook. */
+interface SignOutEvent {
+    user: {
+        id: string;
+        email: string;
+    };
+    timestamp: string;
+}
+/** Payload for auth.onPasswordReset hook. */
+interface PasswordResetEvent {
+    user: {
+        id: string;
+        email: string;
+    };
+    timestamp: string;
+}
+/** Payload for storage.onFileUploaded hook. */
+interface FileUploadedEvent {
+    file: {
+        id: string;
+        name: string;
+        bucket: string;
+        path: string;
+        size: number;
+        contentType: string;
+    };
+}
+/** Payload for storage.onFileDeleted hook. */
+interface FileDeletedEvent {
+    file: {
+        id: string;
+        name: string;
+        bucket: string;
+        path: string;
+    };
+}
+/** Payload for documents.onDocumentCreated hook. */
+interface DocumentCreatedEvent {
+    document: {
+        id: string;
+        collection: string;
+        data: Record<string, unknown>;
+    };
+}
+/** Payload for documents.onDocumentUpdated hook. */
+interface DocumentUpdatedEvent {
+    document: {
+        id: string;
+        collection: string;
+        data: Record<string, unknown>;
+        previousData: Record<string, unknown>;
+    };
+}
+/** Payload for documents.onDocumentDeleted hook. */
+interface DocumentDeletedEvent {
+    document: {
+        id: string;
+        collection: string;
+        data: Record<string, unknown>;
+    };
+}
+type HookHandler<TEvent> = (ctx: HookContext, event: TEvent) => Promise<void>;
+/** Resolved hook configuration (internal). */
+interface ResolvedHook<TEvent = unknown> {
+    module: string;
+    event: string;
+    handler: HookHandler<TEvent>;
+}
+declare const auth: {
+    onUserCreated(handler: HookHandler<UserCreatedEvent>): ResolvedHook<UserCreatedEvent>;
+    onSignIn(handler: HookHandler<SignInEvent>): ResolvedHook<SignInEvent>;
+    onSignOut(handler: HookHandler<SignOutEvent>): ResolvedHook<SignOutEvent>;
+    onPasswordReset(handler: HookHandler<PasswordResetEvent>): ResolvedHook<PasswordResetEvent>;
+};
+declare const storage: {
+    onFileUploaded(handler: HookHandler<FileUploadedEvent>): ResolvedHook<FileUploadedEvent>;
+    onFileDeleted(handler: HookHandler<FileDeletedEvent>): ResolvedHook<FileDeletedEvent>;
+};
+declare const documents: {
+    onDocumentCreated(handler: HookHandler<DocumentCreatedEvent>): ResolvedHook<DocumentCreatedEvent>;
+    onDocumentUpdated(handler: HookHandler<DocumentUpdatedEvent>): ResolvedHook<DocumentUpdatedEvent>;
+    onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
+};
+
+export { type BackoffStrategy, CacheClient, type CustomWebhookConfig, DBClient, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, EndpointContext, type EnvSecretRef, type FileDeletedEvent, type FileUploadedEvent, type HookContext, type HookHandler, HttpError, type JobConfig, type JobContext, Logger, PalbaseBindings, type PasswordResetEvent, type ProviderEventMap, type ProviderWebhookConfig, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, type SignInEvent, type SignOutEvent, type UserCreatedEvent, type WebhookContext, type WebhookEventHandler, type WebhookProvider, type WebhookRequest, type WorkerConfig, auth, defineJob, defineWebhook, defineWorker, documents, storage };