@edge-base/plugin-core 0.1.1

package/README.md

@@ -0,0 +1,165 @@
+<h1 align="center">@edge-base/plugin-core</h1>
+
+<p align="center">
+  <b>Public plugin authoring API for EdgeBase</b><br>
+  Define plugin factories, typed plugin contexts, and plugin testing helpers for the EdgeBase plugin ecosystem
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@edge-base/plugin-core"><img src="https://img.shields.io/npm/v/%40edge-base%2Fplugin-core?color=brightgreen" alt="npm"></a>&nbsp;
+  <a href="https://edgebase.fun/docs/plugins/creating-plugins"><img src="https://img.shields.io/badge/docs-plugins-blue" alt="Docs"></a>&nbsp;
+  <a href="https://github.com/edge-base/edgebase/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="https://edgebase.fun/docs/plugins"><b>Plugins Overview</b></a> ·
+  <a href="https://edgebase.fun/docs/plugins/creating-plugins"><b>Creating Plugins</b></a> ·
+  <a href="https://edgebase.fun/docs/plugins/api-reference"><b>API Reference</b></a> ·
+  <a href="https://edgebase.fun/docs/plugins/using-plugins"><b>Using Plugins</b></a>
+</p>
+
+---
+
+`@edge-base/plugin-core` is the package plugin authors use to build installable EdgeBase plugins.
+
+It gives you:
+
+- `definePlugin()` for typed plugin factories
+- typed contexts for functions, hooks, and migrations
+- public plugin contracts like `PluginDefinition`
+- `createMockContext()` for tests and local validation
+
+This package is for **plugin packages**, not for normal application code.
+
+> Beta: the public plugin contract is usable, but the ecosystem and tooling are still evolving.
+
+## Documentation Map
+
+- [Plugins Overview](https://edgebase.fun/docs/plugins)
+  Understand how plugins fit into an EdgeBase project
+- [Creating Plugins](https://edgebase.fun/docs/plugins/creating-plugins)
+  End-to-end tutorial for building a plugin package
+- [Plugin API Reference](https://edgebase.fun/docs/plugins/api-reference)
+  Public types, contexts, and helper contracts
+- [Using Plugins](https://edgebase.fun/docs/plugins/using-plugins)
+  What host apps do after a plugin exists
+
+## For AI Coding Assistants
+
+This package ships with an `llms.txt` file for AI-assisted plugin development.
+
+You can find it:
+
+- after install: `node_modules/@edge-base/plugin-core/llms.txt`
+- in the repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/plugins/core/llms.txt)
+
+Use it when you want an agent to:
+
+- generate plugin packages with the correct factory shape
+- avoid confusing app code with plugin code
+- use typed `ctx.pluginConfig` and `ctx.admin` correctly
+- model migrations and hooks without guessing unsupported runtime behavior
+
+## Installation
+
+```bash
+npm install @edge-base/plugin-core
+```
+
+If you want a starter layout, you can scaffold one with the CLI:
+
+```bash
+npx --package @edge-base/cli edgebase create-plugin my-plugin
+```
+
+## Quick Start
+
+```ts
+import { definePlugin } from '@edge-base/plugin-core';
+
+interface StripeConfig {
+  secretKey: string;
+}
+
+export const stripePlugin = definePlugin<StripeConfig>({
+  name: '@edge-base/plugin-stripe',
+  version: '0.1.0',
+  tables: {
+    customers: {
+      schema: {
+        email: { type: 'string', required: true },
+      },
+    },
+  },
+  functions: {
+    'create-checkout': {
+      trigger: { type: 'http', method: 'POST' },
+      handler: async (ctx) => {
+        const key = ctx.pluginConfig.secretKey;
+        return Response.json({ ok: true, hasKey: !!key });
+      },
+    },
+  },
+});
+```
+
+`definePlugin()` returns a factory. The host app installs your plugin and calls that factory with user config from its EdgeBase project.
+
+## What This Package Covers
+
+| Area | Included |
+| --- | --- |
+| Plugin factory API | `definePlugin<TConfig>()` |
+| Public plugin contracts | `PluginDefinition`, `PluginFunctionContext`, `PluginHooks`, `PluginMigrationContext` |
+| Plugin admin surface | `ctx.admin` contracts for DB, auth, SQL, KV, D1, Vectorize, push, functions |
+| Testing helpers | `createMockContext()` |
+| Contract version export | `EDGEBASE_PLUGIN_API_VERSION` |
+
+## Typical Plugin Capabilities
+
+With `@edge-base/plugin-core`, a plugin can contribute:
+
+- tables
+- functions
+- auth hooks
+- storage hooks
+- `onInstall` setup
+- semver-keyed migrations
+
+## Testing Plugin Logic
+
+Use `createMockContext()` when you want to test handlers without running a full EdgeBase project:
+
+```ts
+import { createMockContext } from '@edge-base/plugin-core';
+
+const ctx = createMockContext({
+  pluginConfig: { secretKey: 'test-key' },
+});
+```
+
+From there you can call your plugin handlers with a predictable mock context.
+
+## Package Boundary
+
+Reach for this package when you are:
+
+- publishing an EdgeBase plugin to npm
+- sharing reusable EdgeBase functionality across projects
+- building plugin factories that host apps will configure
+
+Do **not** use this package for:
+
+- normal browser app code
+- SSR app code
+- server-side app admin logic
+
+For those, use:
+
+- [`@edge-base/web`](https://www.npmjs.com/package/@edge-base/web)
+- [`@edge-base/ssr`](https://www.npmjs.com/package/@edge-base/ssr)
+- [`@edge-base/admin`](https://www.npmjs.com/package/@edge-base/admin)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,472 @@
+/**
+ * @edge-base/plugin-core — Plugin definition API for EdgeBase.
+ *
+ * Explicit import pattern — plugins are factory functions that return PluginInstance.
+ *
+ * @example
+ * ```typescript
+ * // Plugin author (e.g. @edge-base/plugin-stripe/server/src/index.ts)
+ * import { definePlugin } from '@edge-base/plugin-core';
+ *
+ * interface StripeConfig { secretKey: string; webhookSecret: string; currency?: string }
+ *
+ * export const stripePlugin = definePlugin<StripeConfig>({
+ *   name: '@edge-base/plugin-stripe',
+ *   tables: { customers: { schema: { ... } } },
+ *   functions: {
+ *     'create-checkout': {
+ *       trigger: { type: 'http', method: 'POST' },
+ *       handler: async (ctx) => {
+ *         const key = ctx.pluginConfig.secretKey;  // ← typed
+ *         return Response.json({ ok: true });
+ *       },
+ *     },
+ *   },
+ *   hooks: {
+ *     afterSignUp: async (ctx) => { /* ... *​/ },
+ *   },
+ * });
+ *
+ * // App developer (edgebase.config.ts)
+ * import { stripePlugin } from '@edge-base/plugin-stripe';
+ * export default defineConfig({
+ *   plugins: [ stripePlugin({ secretKey: process.env.STRIPE_SECRET_KEY! }) ],
+ * });
+ * ```
+ */
+import type { PluginInstance, PluginManifest, TableConfig, FunctionTrigger, DbProvider } from '@edge-base/shared';
+export { CURRENT_PLUGIN_API_VERSION as EDGEBASE_PLUGIN_API_VERSION } from '@edge-base/shared';
+export interface PluginTableProxy {
+    insert(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    upsert(data: Record<string, unknown>, options?: {
+        conflictTarget?: string;
+    }): Promise<Record<string, unknown>>;
+    update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    get(id: string): Promise<Record<string, unknown>>;
+    list(options?: {
+        limit?: number;
+        filter?: unknown;
+    }): Promise<{
+        items: Record<string, unknown>[];
+    }>;
+}
+export interface PluginAdminAuthContext {
+    getUser(userId: string): Promise<Record<string, unknown>>;
+    listUsers(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        users: Record<string, unknown>[];
+        cursor?: string;
+    }>;
+    createUser(data: {
+        email: string;
+        password: string;
+        displayName?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>>;
+    updateUser(userId: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    deleteUser(userId: string): Promise<void>;
+    setCustomClaims(userId: string, claims: Record<string, unknown>): Promise<void>;
+    revokeAllSessions(userId: string): Promise<void>;
+}
+/**
+ * Full admin surface available in plugin contexts.
+ * Matches server FunctionAdminContext — all operations bypass access rules.
+ */
+export interface PluginAdminContext {
+    /** Table access on default namespace (shortcut for `db('shared').table(name)`). */
+    table(name: string): PluginTableProxy;
+    /** Access a specific DB namespace instance. */
+    db(namespace: string, id?: string): {
+        table(name: string): PluginTableProxy;
+    };
+    /** Admin user management. */
+    auth: PluginAdminAuthContext;
+    /** Raw SQL on a DB namespace DO. */
+    sql(namespace: string, id: string | undefined, query: string, params?: unknown[]): Promise<unknown[]>;
+    /** Server-side broadcast to a realtime channel. */
+    broadcast(channel: string, event: string, payload?: Record<string, unknown>): Promise<void>;
+    /** Inter-function calls. */
+    functions: {
+        call(name: string, data?: unknown): Promise<unknown>;
+    };
+    /** KV namespace access. */
+    kv(namespace: string): PluginKvProxy;
+    /** D1 database access. */
+    d1(database: string): PluginD1Proxy;
+    /** Vectorize index access. */
+    vector(index: string): PluginVectorProxy;
+    /** Push notification management. */
+    push: PluginPushProxy;
+}
+export interface PluginKvProxy {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: string[];
+        cursor?: string;
+    }>;
+}
+export interface PluginD1Proxy {
+    exec<T = Record<string, unknown>>(query: string, params?: unknown[]): Promise<T[]>;
+}
+export interface PluginVectorProxy {
+    /** Insert or update vectors. */
+    upsert(vectors: Array<{
+        id: string;
+        values: number[];
+        metadata?: Record<string, unknown>;
+        namespace?: string;
+    }>): Promise<{
+        ok: true;
+        count?: number;
+        mutationId?: string;
+    }>;
+    /** Insert new vectors (fails if ID exists). */
+    insert(vectors: Array<{
+        id: string;
+        values: number[];
+        metadata?: Record<string, unknown>;
+        namespace?: string;
+    }>): Promise<{
+        ok: true;
+        count?: number;
+        mutationId?: string;
+    }>;
+    /** Semantic search by vector. */
+    search(vector: number[], options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        namespace?: string;
+        returnValues?: boolean;
+        returnMetadata?: boolean | 'all' | 'indexed' | 'none';
+    }): Promise<Array<{
+        id: string;
+        score: number;
+        values?: number[];
+        metadata?: Record<string, unknown>;
+        namespace?: string;
+    }>>;
+    /** Find similar vectors by an existing vector ID. */
+    queryById(vectorId: string, options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        namespace?: string;
+        returnValues?: boolean;
+        returnMetadata?: boolean | 'all' | 'indexed' | 'none';
+    }): Promise<Array<{
+        id: string;
+        score: number;
+        values?: number[];
+        metadata?: Record<string, unknown>;
+        namespace?: string;
+    }>>;
+    /** Retrieve vectors by IDs. */
+    getByIds(ids: string[]): Promise<Array<{
+        id: string;
+        values?: number[];
+        metadata?: Record<string, unknown>;
+        namespace?: string;
+    }>>;
+    /** Delete vectors by IDs. */
+    delete(ids: string[]): Promise<{
+        ok: true;
+        count?: number;
+        mutationId?: string;
+    }>;
+    /** Get index metadata (dimensions, vector count, metric). */
+    describe(): Promise<{
+        vectorCount: number;
+        dimensions: number;
+        metric: string;
+        id?: string;
+        name?: string;
+        processedUpToDatetime?: string;
+        processedUpToMutation?: string;
+    }>;
+}
+export interface PluginPushProxy {
+    send(userId: string, payload: Record<string, unknown>): Promise<{
+        sent: number;
+        failed: number;
+        removed: number;
+    }>;
+    sendMany(userIds: string[], payload: Record<string, unknown>): Promise<{
+        sent: number;
+        failed: number;
+        removed: number;
+    }>;
+    getTokens(userId: string): Promise<Array<{
+        deviceId: string;
+        platform: string;
+        updatedAt: string;
+        deviceInfo?: Record<string, string>;
+        metadata?: Record<string, unknown>;
+    }>>;
+    getLogs(userId: string, limit?: number): Promise<Array<{
+        sentAt: string;
+        userId: string;
+        platform: string;
+        status: string;
+        collapseId?: string;
+        error?: string;
+    }>>;
+    sendToToken(token: string, payload: Record<string, unknown>, platform?: string): Promise<{
+        sent: number;
+        failed: number;
+        error?: string;
+    }>;
+    sendToTopic(topic: string, payload: Record<string, unknown>): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    broadcast(payload: Record<string, unknown>): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Context passed to plugin function handlers.
+ * Mirrors the server FunctionContext — admin surface matches FunctionAdminContext exactly.
+ *
+ * @typeParam TConfig - Plugin config shape from definePlugin<TConfig>()
+ */
+export interface PluginFunctionContext<TConfig = Record<string, unknown>> {
+    /** The incoming HTTP request. */
+    request: Request;
+    /** Authenticated user (null if unauthenticated). */
+    auth: {
+        id: string;
+        email?: string;
+        isAnonymous?: boolean;
+        custom?: Record<string, unknown>;
+    } | null;
+    /** Plugin-specific config — typed via definePlugin<TConfig>(). Injected by factory closure. */
+    pluginConfig: TConfig;
+    /** Route parameters extracted from trigger path (e.g. `/stripe/[id]` → `{ id: '...' }`). */
+    params: Record<string, string>;
+    /** Server-side EdgeBase admin client (admin-level access — bypasses access rules). */
+    admin: PluginAdminContext;
+    /** Trigger data (before/after for DB triggers). */
+    data?: {
+        before?: Record<string, unknown>;
+        after?: Record<string, unknown>;
+    };
+}
+/**
+ * Context passed to plugin storage hook handlers.
+ * Storage hooks receive file metadata only — NO file content (Worker 128MB memory limit).
+ * Blocking hooks (`before*`) can throw to reject. Non-blocking hooks (`after*`) run via waitUntil.
+ */
+export interface PluginStorageHookContext<TConfig = Record<string, unknown>> {
+    file: {
+        key: string;
+        bucket: string;
+        size: number;
+        contentType: string;
+        etag?: string;
+        uploadedAt?: string;
+        uploadedBy?: string | null;
+        customMetadata?: Record<string, string>;
+    };
+    /** Authenticated user who performed the action (null for service key or unauthenticated). */
+    auth: {
+        id: string;
+        email?: string;
+    } | null;
+    /** Plugin-specific config injected by factory closure. */
+    pluginConfig: TConfig;
+    /** Server-side admin client — access to DB, KV, D1, Vectorize, push, etc. */
+    admin: PluginAdminContext;
+}
+/**
+ * Context passed to plugin onInstall and migration handlers.
+ * Provides admin-level access for schema alterations, data migrations, and service setup.
+ *
+ * NOTE: Some admin methods (kv, d1, vector, broadcast, functions, push) require workerUrl
+ * which is derived from the first incoming request. These will throw if workerUrl is unavailable.
+ */
+export interface PluginMigrationContext<TConfig = Record<string, unknown>> {
+    /** Plugin-specific config injected by factory closure. */
+    pluginConfig: TConfig;
+    /** Admin context for DB operations and service access. */
+    admin: PluginAdminContext;
+    /** Previous plugin version (null for onInstall / first deploy). */
+    previousVersion: string | null;
+}
+/**
+ * Context passed to plugin auth hook handlers.
+ * Mirrors the server's executeAuthHook context with full admin access.
+ */
+export interface PluginHookContext<TConfig = Record<string, unknown>> {
+    request: Request;
+    auth: null;
+    /** Server-side admin client with full resource access. */
+    admin: PluginAdminContext;
+    data: {
+        after: Record<string, unknown>;
+    };
+    pluginConfig: TConfig;
+}
+export interface PluginHooks<TConfig = Record<string, unknown>> {
+    /** Before user creation. Throw to reject signup. 5s timeout. */
+    beforeSignUp?: (ctx: PluginHookContext<TConfig>) => Promise<Record<string, unknown> | void>;
+    /** After user creation. Non-blocking (waitUntil). */
+    afterSignUp?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** Before session creation. Throw to reject signin. 5s timeout. */
+    beforeSignIn?: (ctx: PluginHookContext<TConfig>) => Promise<Record<string, unknown> | void>;
+    /** After session creation. Non-blocking (waitUntil). */
+    afterSignIn?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** On JWT refresh. Return a plain object of claim overrides. 5s timeout. */
+    onTokenRefresh?: (ctx: PluginHookContext<TConfig>) => Promise<Record<string, unknown> | void>;
+    /** Before password reset. Throw to reject. 5s timeout. */
+    beforePasswordReset?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** After password reset. Non-blocking (waitUntil). */
+    afterPasswordReset?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** Before sign out. Throw to reject. 5s timeout. */
+    beforeSignOut?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** After sign out. Non-blocking (waitUntil). */
+    afterSignOut?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** On account deletion. Non-blocking (waitUntil). */
+    onDeleteAccount?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** On email verification. Non-blocking (waitUntil). */
+    onEmailVerified?: (ctx: PluginHookContext<TConfig>) => Promise<void>;
+    /** Before upload. Return Record<string,string> to merge custom metadata. Throw to reject. 5s timeout. */
+    beforeUpload?: (ctx: PluginStorageHookContext<TConfig>) => Promise<Record<string, string> | void>;
+    /** Before file deletion. Throw to reject. 5s timeout. */
+    beforeDelete?: (ctx: PluginStorageHookContext<TConfig>) => Promise<void>;
+    /** Before file download. Throw to reject. 5s timeout. */
+    beforeDownload?: (ctx: PluginStorageHookContext<TConfig>) => Promise<void>;
+    /** After upload. Non-blocking (waitUntil). Receives final R2 metadata. */
+    afterUpload?: (ctx: PluginStorageHookContext<TConfig>) => Promise<void>;
+    /** After deletion. Non-blocking (waitUntil). */
+    afterDelete?: (ctx: PluginStorageHookContext<TConfig>) => Promise<void>;
+    /** On metadata update. Non-blocking (waitUntil). */
+    onMetadataUpdate?: (ctx: PluginStorageHookContext<TConfig>) => Promise<void>;
+}
+export interface PluginDefinition<TConfig = Record<string, unknown>> {
+    /** Plugin unique name (e.g. '@edge-base/plugin-stripe'). */
+    name: string;
+    /**
+     * Public plugin contract version.
+     * Defaults to the current runtime contract when omitted.
+     */
+    pluginApiVersion?: number;
+    /** Semantic version string (e.g. '1.0.0'). Required for migration support. */
+    version?: string;
+    /** Serializable metadata used by CLI/docs tooling. */
+    manifest?: PluginManifest;
+    /** Plugin tables. Keys = table names (plugin.name/ prefix added automatically). */
+    tables?: Record<string, TableConfig>;
+    /** DB block for plugin tables. Default: 'shared'. */
+    dbBlock?: string;
+    /**
+     * Database provider required by this plugin.
+     * - `'do'` (default): Durable Object + SQLite
+     * - `'neon'`: Requires Neon PostgreSQL and a configured connection string
+     * - `'postgres'`: Requires custom PostgreSQL
+     */
+    provider?: DbProvider;
+    /** Plugin functions. Keys = function names (plugin.name/ prefix added automatically). */
+    functions?: Record<string, {
+        trigger: FunctionTrigger;
+        handler: (ctx: PluginFunctionContext<TConfig>) => Promise<Response | unknown>;
+    }>;
+    /** Auth + storage hooks. */
+    hooks?: PluginHooks<TConfig>;
+    /** Runs once on first deploy with this plugin. Use for initial seed data, external webhook registration, etc. */
+    onInstall?: (ctx: PluginMigrationContext<TConfig>) => Promise<void>;
+    /**
+     * Version-keyed migration functions. Run in semver order on deploy when plugin version changes.
+     * Migrations MUST be idempotent — concurrent Worker instances may execute the same migration.
+     * Use either onInstall OR migrations['1.0.0'], not both (onInstall runs first, then migrations).
+     */
+    migrations?: Record<string, (ctx: PluginMigrationContext<TConfig>) => Promise<void>>;
+}
+/**
+ * Define an EdgeBase plugin. Returns a factory function that takes user config
+ * and returns a PluginInstance for use in edgebase.config.ts.
+ *
+ * The factory closure captures userConfig so every handler receives pluginConfig
+ * without the server needing to know about plugins.
+ *
+ * @typeParam TConfig - Shape of the plugin config
+ *
+ * @example
+ * ```typescript
+ * export const stripePlugin = definePlugin<{ secretKey: string }>({
+ *   name: '@edge-base/plugin-stripe',
+ *   tables: { customers: { schema: { ... } } },
+ *   functions: {
+ *     'create-checkout': {
+ *       trigger: { type: 'http', method: 'POST' },
+ *       handler: async (ctx) => {
+ *         const key = ctx.pluginConfig.secretKey;  // typed, injected by closure
+ *         return Response.json({ ok: true });
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function definePlugin<TConfig>(definition: PluginDefinition<TConfig>): (userConfig: TConfig) => PluginInstance;
+/**
+ * Create a mock PluginFunctionContext for unit testing plugin handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createMockContext } from '@edge-base/plugin-core';
+ *
+ * const ctx = createMockContext({
+ *   auth: { id: 'user-1' },
+ *   pluginConfig: { secretKey: 'sk_test_xxx' },
+ *   body: { priceId: 'price_xxx' },
+ * });
+ * const response = await myHandler(ctx);
+ * expect(response.status).toBe(200);
+ * ```
+ */
+export declare function createMockContext<TConfig = Record<string, unknown>>(options?: {
+    auth?: PluginFunctionContext['auth'];
+    pluginConfig?: TConfig;
+    params?: Record<string, string>;
+    body?: unknown;
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}): PluginFunctionContext<TConfig>;
+/**
+ * Base interface for plugin client SDKs.
+ * Use this as a guide when creating typed client wrappers.
+ *
+ * @example
+ * ```typescript
+ * import type { PluginClientFactory } from '@edge-base/plugin-core';
+ *
+ * interface StripeClient { createCheckout(params: CheckoutParams): Promise<CheckoutResult>; }
+ *
+ * export const createStripePlugin: PluginClientFactory<StripeClient> = (client) => ({
+ *   async createCheckout(params) {
+ *     return client.functions.call('@edge-base/plugin-stripe/create-checkout', params) as Promise<CheckoutResult>;
+ *   },
+ * });
+ * ```
+ */
+export interface PluginClientHost {
+    table(name: string): unknown;
+    functions: {
+        call(name: string, data?: unknown): Promise<unknown>;
+    };
+}
+export type PluginClientFactory<T> = (client: PluginClientHost) => T;

package/dist/index.js

@@ -0,0 +1,319 @@
+/**
+ * @edge-base/plugin-core — Plugin definition API for EdgeBase.
+ *
+ * Explicit import pattern — plugins are factory functions that return PluginInstance.
+ *
+ * @example
+ * ```typescript
+ * // Plugin author (e.g. @edge-base/plugin-stripe/server/src/index.ts)
+ * import { definePlugin } from '@edge-base/plugin-core';
+ *
+ * interface StripeConfig { secretKey: string; webhookSecret: string; currency?: string }
+ *
+ * export const stripePlugin = definePlugin<StripeConfig>({
+ *   name: '@edge-base/plugin-stripe',
+ *   tables: { customers: { schema: { ... } } },
+ *   functions: {
+ *     'create-checkout': {
+ *       trigger: { type: 'http', method: 'POST' },
+ *       handler: async (ctx) => {
+ *         const key = ctx.pluginConfig.secretKey;  // ← typed
+ *         return Response.json({ ok: true });
+ *       },
+ *     },
+ *   },
+ *   hooks: {
+ *     afterSignUp: async (ctx) => { /* ... *​/ },
+ *   },
+ * });
+ *
+ * // App developer (edgebase.config.ts)
+ * import { stripePlugin } from '@edge-base/plugin-stripe';
+ * export default defineConfig({
+ *   plugins: [ stripePlugin({ secretKey: process.env.STRIPE_SECRET_KEY! }) ],
+ * });
+ * ```
+ */
+import { CURRENT_PLUGIN_API_VERSION } from '@edge-base/shared';
+export { CURRENT_PLUGIN_API_VERSION as EDGEBASE_PLUGIN_API_VERSION } from '@edge-base/shared';
+// ─── definePlugin() — Factory Pattern ───
+/**
+ * Define an EdgeBase plugin. Returns a factory function that takes user config
+ * and returns a PluginInstance for use in edgebase.config.ts.
+ *
+ * The factory closure captures userConfig so every handler receives pluginConfig
+ * without the server needing to know about plugins.
+ *
+ * @typeParam TConfig - Shape of the plugin config
+ *
+ * @example
+ * ```typescript
+ * export const stripePlugin = definePlugin<{ secretKey: string }>({
+ *   name: '@edge-base/plugin-stripe',
+ *   tables: { customers: { schema: { ... } } },
+ *   functions: {
+ *     'create-checkout': {
+ *       trigger: { type: 'http', method: 'POST' },
+ *       handler: async (ctx) => {
+ *         const key = ctx.pluginConfig.secretKey;  // typed, injected by closure
+ *         return Response.json({ ok: true });
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function definePlugin(definition) {
+    return (userConfig) => {
+        // Wrap function handlers with pluginConfig closure
+        const functions = {};
+        if (definition.functions) {
+            for (const [name, def] of Object.entries(definition.functions)) {
+                functions[name] = {
+                    trigger: def.trigger,
+                    handler: async (ctx) => {
+                        ctx.pluginConfig = userConfig;
+                        return def.handler(ctx);
+                    },
+                };
+            }
+        }
+        // Wrap auth + storage hooks with pluginConfig closure
+        const hooks = {};
+        if (definition.hooks) {
+            for (const [event, hookFn] of Object.entries(definition.hooks)) {
+                if (hookFn) {
+                    hooks[event] = async (ctx) => {
+                        ctx.pluginConfig = userConfig;
+                        return hookFn(ctx);
+                    };
+                }
+            }
+        }
+        // Wrap onInstall with pluginConfig closure
+        let onInstall;
+        if (definition.onInstall) {
+            const installFn = definition.onInstall;
+            onInstall = async (ctx) => {
+                ctx.pluginConfig = userConfig;
+                return installFn(ctx);
+            };
+        }
+        // Wrap migrations with pluginConfig closure
+        let migrations;
+        if (definition.migrations) {
+            migrations = {};
+            for (const [version, migrateFn] of Object.entries(definition.migrations)) {
+                migrations[version] = async (ctx) => {
+                    ctx.pluginConfig = userConfig;
+                    return migrateFn(ctx);
+                };
+            }
+        }
+        return {
+            name: definition.name,
+            pluginApiVersion: definition.pluginApiVersion ?? CURRENT_PLUGIN_API_VERSION,
+            version: definition.version,
+            manifest: definition.manifest,
+            config: userConfig,
+            tables: definition.tables,
+            dbBlock: definition.dbBlock,
+            provider: definition.provider,
+            functions: Object.keys(functions).length > 0 ? functions : undefined,
+            hooks: Object.keys(hooks).length > 0 ? hooks : undefined,
+            onInstall,
+            migrations,
+        };
+    };
+}
+// ─── Testing Utilities ───
+/**
+ * Create a mock PluginFunctionContext for unit testing plugin handlers.
+ *
+ * @example
+ * ```typescript
+ * import { createMockContext } from '@edge-base/plugin-core';
+ *
+ * const ctx = createMockContext({
+ *   auth: { id: 'user-1' },
+ *   pluginConfig: { secretKey: 'sk_test_xxx' },
+ *   body: { priceId: 'price_xxx' },
+ * });
+ * const response = await myHandler(ctx);
+ * expect(response.status).toBe(200);
+ * ```
+ */
+export function createMockContext(options) {
+    const method = options?.method ?? 'POST';
+    const url = options?.url ?? 'http://localhost:8787/api/functions/test';
+    const headers = new Headers(options?.headers);
+    if (options?.body)
+        headers.set('Content-Type', 'application/json');
+    const request = new Request(url, {
+        method,
+        headers,
+        body: options?.body ? JSON.stringify(options.body) : undefined,
+    });
+    // In-memory table store for testing
+    const stores = {};
+    function getStore(name) {
+        if (!stores[name])
+            stores[name] = new Map();
+        return stores[name];
+    }
+    function createTableProxy(name) {
+        const store = getStore(name);
+        return {
+            async insert(data) {
+                const id = data.id ?? crypto.randomUUID();
+                const doc = { id, ...data, createdAt: new Date().toISOString() };
+                store.set(id, doc);
+                return doc;
+            },
+            async upsert(data, options) {
+                const conflictTarget = options?.conflictTarget ?? 'id';
+                const existing = Array.from(store.values()).find((doc) => doc[conflictTarget] !== undefined && doc[conflictTarget] === data[conflictTarget]);
+                if (existing) {
+                    const id = String(existing.id ?? data.id ?? crypto.randomUUID());
+                    const updated = {
+                        ...existing,
+                        ...data,
+                        id,
+                        updatedAt: new Date().toISOString(),
+                    };
+                    store.set(id, updated);
+                    return updated;
+                }
+                const id = data.id ?? crypto.randomUUID();
+                const doc = { id, ...data, createdAt: new Date().toISOString() };
+                store.set(id, doc);
+                return doc;
+            },
+            async update(id, data) {
+                const existing = store.get(id) ?? {};
+                const updated = { ...existing, ...data, updatedAt: new Date().toISOString() };
+                store.set(id, updated);
+                return updated;
+            },
+            async delete(id) {
+                const existed = store.has(id);
+                store.delete(id);
+                return { deleted: existed };
+            },
+            async get(id) {
+                return store.get(id) ?? null;
+            },
+            async list() {
+                return { items: Array.from(store.values()) };
+            },
+        };
+    }
+    const mockAuth = {
+        async getUser() {
+            return {};
+        },
+        async listUsers() {
+            return { users: [] };
+        },
+        async createUser() {
+            return {};
+        },
+        async updateUser() {
+            return {};
+        },
+        async deleteUser() { },
+        async setCustomClaims() { },
+        async revokeAllSessions() { },
+    };
+    const mockPush = {
+        async send() {
+            return { sent: 0, failed: 0, removed: 0 };
+        },
+        async sendMany() {
+            return { sent: 0, failed: 0, removed: 0 };
+        },
+        async getTokens() {
+            return [];
+        },
+        async getLogs() {
+            return [];
+        },
+        async sendToToken() {
+            return { sent: 0, failed: 0 };
+        },
+        async sendToTopic() {
+            return { success: true };
+        },
+        async broadcast() {
+            return { success: true };
+        },
+    };
+    const mockAdmin = {
+        table: createTableProxy,
+        db(_namespace, _id) {
+            return { table: createTableProxy };
+        },
+        auth: mockAuth,
+        async sql() {
+            return [];
+        },
+        async broadcast() { },
+        functions: {
+            async call() {
+                return {};
+            },
+        },
+        kv() {
+            return {
+                async get() {
+                    return null;
+                },
+                async set() { },
+                async delete() { },
+                async list() {
+                    return { keys: [] };
+                },
+            };
+        },
+        d1() {
+            return {
+                async exec() {
+                    return [];
+                },
+            };
+        },
+        vector() {
+            return {
+                async upsert() {
+                    return { ok: true, count: 0 };
+                },
+                async insert() {
+                    return { ok: true, count: 0 };
+                },
+                async search() {
+                    return [];
+                },
+                async queryById() {
+                    return [];
+                },
+                async getByIds() {
+                    return [];
+                },
+                async delete() {
+                    return { ok: true, count: 0 };
+                },
+                async describe() {
+                    return { vectorCount: 0, dimensions: 0, metric: 'cosine' };
+                },
+            };
+        },
+        push: mockPush,
+    };
+    return {
+        request,
+        auth: options?.auth ?? null,
+        pluginConfig: (options?.pluginConfig ?? {}),
+        params: options?.params ?? {},
+        admin: mockAdmin,
+    };
+}

package/llms.txt

@@ -0,0 +1,105 @@
+# EdgeBase Plugin Core
+
+Use this file as a quick-reference contract for AI coding assistants working with `@edge-base/plugin-core`.
+
+## Package Boundary
+
+Use `@edge-base/plugin-core` for authoring installable EdgeBase plugins.
+
+Do not use it for regular application code. For browser apps use `@edge-base/web`. For trusted server code use `@edge-base/admin`. For SSR cookie helpers use `@edge-base/ssr`.
+
+## Source Of Truth
+
+- Package README: https://github.com/edge-base/edgebase/blob/main/packages/plugins/core/README.md
+- Plugins overview: https://edgebase.fun/docs/plugins
+- Creating plugins: https://edgebase.fun/docs/plugins/creating-plugins
+- Plugin API reference: https://edgebase.fun/docs/plugins/api-reference
+- Using plugins: https://edgebase.fun/docs/plugins/using-plugins
+
+## Canonical Examples
+
+### Define a plugin
+
+```ts
+import { definePlugin } from '@edge-base/plugin-core';
+
+interface MyPluginConfig {
+  apiKey: string;
+}
+
+export const myPlugin = definePlugin<MyPluginConfig>({
+  name: 'my-plugin',
+  version: '0.1.0',
+  tables: {
+    items: {
+      schema: {
+        title: { type: 'string', required: true },
+      },
+    },
+  },
+  functions: {
+    ping: {
+      trigger: { type: 'http', method: 'GET' },
+      handler: async (ctx) => {
+        return Response.json({
+          ok: true,
+          configured: !!ctx.pluginConfig.apiKey,
+        });
+      },
+    },
+  },
+});
+```
+
+### Use plugin config inside a hook
+
+```ts
+hooks: {
+  afterSignUp: async (ctx) => {
+    const apiKey = ctx.pluginConfig.apiKey;
+    await ctx.admin.table('my-plugin/customers').insert({
+      userId: ctx.data.after.id,
+      apiKeyPresent: !!apiKey,
+    });
+  },
+}
+```
+
+### Use mock context in tests
+
+```ts
+import { createMockContext } from '@edge-base/plugin-core';
+
+const ctx = createMockContext({
+  pluginConfig: { apiKey: 'test-key' },
+});
+```
+
+## Hard Rules
+
+- `definePlugin<TConfig>()` returns a factory: `(userConfig: TConfig) => PluginInstance`
+- `ctx.pluginConfig` is injected automatically into plugin functions, hooks, `onInstall`, and migrations
+- plugin table and function keys are local names; EdgeBase applies plugin namespacing at integration time
+- `ctx.admin` is an admin-level surface and bypasses access rules
+- `dbBlock` defaults to `'shared'` when omitted
+- `provider` defaults to `'do'` when omitted
+- semver-keyed migrations must be idempotent
+- `EDGEBASE_PLUGIN_API_VERSION` is only needed when manually constructing a `PluginInstance`; normal plugin authors should rely on `definePlugin()`
+
+## Common Mistakes
+
+- do not export a raw `PluginInstance` unless you have a strong reason; use `definePlugin()`
+- do not assume plugin code runs in a separate server process; it is bundled into the same EdgeBase runtime
+- do not put app-specific secrets directly in module scope when they should come from `userConfig`
+- do not treat plugin tables as globally named; plugin namespacing matters
+- do not use this package for normal app code imports
+
+## Quick Reference
+
+```text
+definePlugin<TConfig>(definition)           -> returns plugin factory
+createMockContext(options?)                 -> mock typed context for tests
+EDGEBASE_PLUGIN_API_VERSION                 -> public plugin contract version
+ctx.pluginConfig                            -> plugin instance config captured by closure
+ctx.admin                                   -> admin-level server access inside plugin handlers
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@edge-base/plugin-core",
+    "version": "0.1.1",
+    "description": "EdgeBase plugin authoring helpers and public plugin contracts",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/edge-base/edgebase.git",
+        "directory": "packages/plugins/core"
+    },
+    "homepage": "https://edgebase.fun",
+    "bugs": "https://github.com/edge-base/edgebase/issues",
+    "keywords": [
+        "edgebase",
+        "plugins",
+        "plugin-api"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "llms.txt"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "prepack": "pnpm run build"
+    },
+    "dependencies": {
+        "@edge-base/shared": "workspace:*"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0"
+    }
+}