@every-app/sdk 0.3.0-rc.3 → 0.3.0-rc.5

package/dist/manifest.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The manifest an app author writes as `everyapp.config.ts`, typed:
+ *
+ *   import { defineEveryApp } from "@every-app/sdk";
+ *
+ *   export default defineEveryApp({
+ *     id: "notes",
+ *     name: "Notes",
+ *     resources: { d1: ["DB"] },
+ *   });
+ *
+ * Types only, and a leaf module: `cloudflare.config.ts` imports the manifest,
+ * and the Cloudflare Vite plugin hides from the Worker every file the config
+ * imports. The rules beyond the shape (which ids exist, which names are
+ * reserved, which scope sets a provider has) are the CLI's: `everyapp deploy`
+ * and `everyapp dev` validate the manifest and say what is wrong. The
+ * perimeter's schema (`@every-app/perimeter/manifest`) is held to this type
+ * by a test there.
+ *
+ * The Worker reads the manifest back as `env.EVERYAPP_MANIFEST`, which
+ * `everyAppWorker()` sets and `cf workers types` types from the file.
+ */
+/** Why a setting is needed and whether the app opens without it (the settings model). */
+export interface EveryAppSettingNeed {
+    /** Why the app needs it, for whoever sets it. At most 200 characters. */
+    readonly why?: string;
+    /** An https page that says where the key or client comes from. */
+    readonly docs?: string;
+    /** The app opens without it; the feature using it says what is missing. */
+    readonly optional?: boolean;
+    /** The group of which one member is enough ("AI model"). */
+    readonly anyOf?: string;
+}
+/** A route reachable without a signed-in member. */
+export interface EveryAppPublicRoute {
+    /** Absolute glob: `*` matches one segment, `**` one or more. */
+    readonly path: string;
+    /** The methods it answers; `["GET"]` when left out. */
+    readonly methods?: readonly string[];
+}
+/** A Durable Object or Workflow class: its binding, the class, and the helper Worker that defines it. */
+export interface EveryAppClassResource {
+    readonly name: string;
+    readonly className: string;
+    readonly worker?: string;
+}
+/** A Cloudflare Queue's consumer settings. */
+export interface EveryAppQueueConsumer {
+    readonly worker?: string;
+    readonly maxBatchSize?: number;
+    readonly maxBatchTimeout?: number;
+    readonly maxRetries?: number;
+    readonly maxConcurrency?: number | null;
+    readonly retryDelay?: number;
+    readonly visibilityTimeoutMs?: number;
+    readonly deadLetterQueue?: string;
+}
+/** Cloudflare's limits for one of the app's Workers. */
+export interface EveryAppWorkerLimits {
+    /** CPU milliseconds an invocation may use, up to 300000. */
+    readonly cpuMs?: number;
+}
+/** The Cloudflare resources the app's Workers bind; the deploy creates them. */
+export interface EveryAppResources {
+    readonly d1?: readonly string[];
+    readonly kv?: readonly string[];
+    readonly r2?: readonly string[];
+    readonly durableObjects?: readonly EveryAppClassResource[];
+    readonly workflows?: readonly EveryAppClassResource[];
+    readonly hyperdrive?: readonly {
+        readonly name: string;
+        readonly worker?: string;
+        readonly caching?: "off" | "default";
+    }[];
+    readonly queues?: readonly {
+        readonly name: string;
+        readonly consumer?: true | EveryAppQueueConsumer;
+    }[];
+    readonly ai?: readonly string[];
+    readonly browser?: readonly string[];
+    readonly images?: readonly string[];
+    readonly vectorize?: readonly {
+        readonly name: string;
+        readonly dimensions?: number;
+        readonly metric?: "cosine" | "euclidean" | "dot-product";
+        /** A Workers AI embedding model's shape, instead of `dimensions` and `metric`. */
+        readonly preset?: "@cf/baai/bge-small-en-v1.5" | "@cf/baai/bge-base-en-v1.5" | "@cf/baai/bge-large-en-v1.5" | "openai/text-embedding-ada-002" | "cohere/embed-multilingual-v2.0";
+    }[];
+    readonly aiGateway?: readonly {
+        readonly name: string;
+        readonly collectLogs?: boolean;
+        readonly cacheTtl?: number;
+    }[];
+    readonly sendEmail?: readonly {
+        readonly name: string;
+        readonly allowedSenderAddresses: readonly string[];
+        readonly destinationAddress?: string;
+        readonly allowedDestinationAddresses?: readonly string[];
+    }[];
+    readonly secretsStore?: readonly {
+        readonly name: string;
+    }[];
+    readonly analyticsEngine?: readonly {
+        readonly name: string;
+        readonly dataset?: string;
+    }[];
+}
+/** One capability the Gateway serves the app with keys it holds. */
+export interface EveryAppCapabilityEntry extends EveryAppSettingNeed {
+    readonly access: "read" | "write";
+    /** An OAuth client's scope sets, by name (`["gmail.read"]`). */
+    readonly scopes?: readonly string[];
+}
+/** One of the app's own secrets, with its need. */
+export interface EveryAppSecretEntry extends EveryAppSettingNeed {
+    readonly name: string;
+    /** Its guide in the everyapp skill (`"setup/main-secret.md"`). */
+    readonly setup?: string;
+}
+/** `everyapp.config.ts`. */
+export interface EveryAppManifest {
+    /** Stable id, kebab-case: the app's hostname and Worker. */
+    readonly id: string;
+    readonly name?: string;
+    /** The one line the Gateway's app library shows under the name. */
+    readonly description?: string;
+    /** The path of an SVG the app serves (`"/everyapp-icon.svg"`). */
+    readonly icon?: string;
+    /** Legacy: the entry comes from `cloudflare.config.ts`. */
+    readonly main?: string;
+    /** YYYY-MM-DD. */
+    readonly compatibilityDate?: string;
+    readonly resources?: EveryAppResources;
+    /** Helper Workers deployed beside the app's as `<app worker>--<name>`. */
+    readonly workers?: readonly {
+        readonly name: string;
+        readonly binding?: string;
+        readonly limits?: EveryAppWorkerLimits;
+    }[];
+    readonly database?: {
+        readonly provider: "d1" | "postgres";
+        /** A cloud region such as `"aws:us-east-1"`. */
+        readonly region?: string;
+    };
+    readonly limits?: EveryAppWorkerLimits;
+    /** Routes open without a signed-in member. Default: none. */
+    readonly public?: readonly EveryAppPublicRoute[];
+    /** AI providers the Gateway calls for the app, by id or with their need. */
+    readonly providers?: readonly (string | (EveryAppSettingNeed & {
+        readonly id: string;
+    }))[];
+    /** Capabilities by id (`members`, `email`, `dataforseo`, …). */
+    readonly capabilities?: {
+        readonly [id: string]: EveryAppCapabilityEntry;
+    };
+    /** The app's own secrets, by name or with their need. */
+    readonly secrets?: readonly (string | EveryAppSecretEntry)[];
+    /** App-domain scopes personal access tokens may request, with descriptions. */
+    readonly scopes?: {
+        readonly [scope: string]: string;
+    };
+    readonly ai?: {
+        /** Model ids the app may request; any other is `model_not_allowed`. */
+        readonly models?: readonly string[];
+        /** OpenAI API paths beyond inference (`"/v1/files"`). */
+        readonly routes?: readonly string[];
+        /** The app takes the Gateway's default chat model (`ai()`). */
+        readonly chat?: boolean | EveryAppSettingNeed;
+    };
+    /** `inbound: true`: the Worker exports an `email()` handler. */
+    readonly email?: {
+        readonly inbound?: boolean;
+    };
+    /** Who can open the app once registered; `"admins"` by default. */
+    readonly access?: "everyone" | "admins";
+    readonly serverFnGuard?: boolean;
+    readonly serverFnBase?: string;
+    /** Shell command that builds the app; `cf build` by default. */
+    readonly build?: string;
+    /** Shell command `everyapp dev` starts; it must listen on PORT. */
+    readonly dev?: string;
+    /** Legacy: the port comes from PORT. */
+    readonly devPort?: number;
+    /** Dependency install command; false skips it. */
+    readonly install?: false | string;
+    readonly migrations?: {
+        readonly engine: "drizzle" | "d1-sql" | "prisma";
+        readonly dialect?: "sqlite" | "postgresql";
+        readonly dir?: string;
+        readonly config?: string;
+        readonly binding?: string;
+    };
+    /** Who answers `/mcp` on the app's own host, and why it needs to. */
+    readonly mcp?: {
+        readonly by: "gateway" | "app";
+        readonly why: string;
+    };
+}
+/**
+ * Type `everyapp.config.ts` without widening it: the literal binding names
+ * stay, so `everyAppWorker()` types `env.DB` and `env.EVERYAPP_MANIFEST`
+ * from them. Returns the manifest as given.
+ */
+export declare function defineEveryApp<const M extends EveryAppManifest>(manifest: M): M;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/manifest.js

@@ -0,0 +1,30 @@
+/**
+ * The manifest an app author writes as `everyapp.config.ts`, typed:
+ *
+ *   import { defineEveryApp } from "@every-app/sdk";
+ *
+ *   export default defineEveryApp({
+ *     id: "notes",
+ *     name: "Notes",
+ *     resources: { d1: ["DB"] },
+ *   });
+ *
+ * Types only, and a leaf module: `cloudflare.config.ts` imports the manifest,
+ * and the Cloudflare Vite plugin hides from the Worker every file the config
+ * imports. The rules beyond the shape (which ids exist, which names are
+ * reserved, which scope sets a provider has) are the CLI's: `everyapp deploy`
+ * and `everyapp dev` validate the manifest and say what is wrong. The
+ * perimeter's schema (`@every-app/perimeter/manifest`) is held to this type
+ * by a test there.
+ *
+ * The Worker reads the manifest back as `env.EVERYAPP_MANIFEST`, which
+ * `everyAppWorker()` sets and `cf workers types` types from the file.
+ */
+/**
+ * Type `everyapp.config.ts` without widening it: the literal binding names
+ * stay, so `everyAppWorker()` types `env.DB` and `env.EVERYAPP_MANIFEST`
+ * from them. Returns the manifest as given.
+ */
+export function defineEveryApp(manifest) {
+    return manifest;
+}

package/dist/server/ai.d.ts

@@ -41,5 +41,26 @@ export declare const AI_DEFAULT_BASE_URL = "http://every-app-gateway.internal/ap
  * `createGatewayFetch` does (no binding and no dev key) and
  * `AttributionError` where a shared app's call says nobody's.
  */
+export declare function ai(options: CreateGatewayFetchOptions & {
+    optional: true;
+}): AiClient | null;
 export declare function ai(options: CreateGatewayFetchOptions): AiClient;
+/**
+ * A provider's root behind the Gateway, `http://every-app-gateway.internal/api/ai/<provider>`:
+ * join the provider's own paths onto it (`/api/v1/chat/completions` for
+ * OpenRouter) and send them with `createGatewayFetch()`. For an OpenAI
+ * client's `baseURL`, use {@link aiBaseUrl}.
+ */
+export declare function providerBaseUrl(provider: string): string;
+/**
+ * The OpenAI-compatible base URL of `provider` behind the Gateway, for an
+ * OpenAI client's `baseURL` (with `fetch: createGatewayFetch(...)`):
+ * `default` (the default) is {@link AI_DEFAULT_BASE_URL},
+ * `…/api/ai/default/v1`; a catalog provider's is its root and the prefix
+ * of its chat route (`…/api/ai/openrouter/api/v1`, `…/api/ai/workers-ai/v1`,
+ * `…/api/ai/openai/v1`). Throws `ConfigurationError` for a provider with
+ * no OpenAI-compatible chat route (Cohere): call {@link providerBaseUrl}
+ * with its own paths instead.
+ */
+export declare function aiBaseUrl(provider?: string): string;
 //# sourceMappingURL=ai.d.ts.map

package/dist/server/ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/server/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,OAAO,gBAAgB,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,wDAAuD,CAAC;AAExF;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,OAAO,EAAE,yBAAyB,GAAG,QAAQ,CAQ/D"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/server/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,gBAAgB,EAIjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,OAAO,gBAAgB,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,wDAAuD,CAAC;AAExF;;;;;GAKG;AACH,wBAAgB,EAAE,CAChB,OAAO,EAAE,yBAAyB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GACtD,QAAQ,GAAG,IAAI,CAAC;AACnB,wBAAgB,EAAE,CAAC,OAAO,EAAE,yBAAyB,GAAG,QAAQ,CAAC;AAejE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,QAAQ,GAAE,MAA4B,GAAG,MAAM,CAaxE"}

package/dist/server/ai.js

@@ -19,22 +19,51 @@
  * fallback). An app that needs one provider in particular keeps listing it
  * under `providers` and calling `/api/ai/<provider>/…`.
  */
-import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER } from "../internal/index.js";
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, CATALOG, ConfigurationError, } from "../internal/index.js";
 import { BINDING_ORIGIN, createGatewayFetch, } from "./gatewayFetch.js";
 /** The base URL of the default route, as the SDK and the docs name it. */
 export const AI_DEFAULT_BASE_URL = `${BINDING_ORIGIN}/api/ai/${AI_DEFAULT_PROVIDER}/v1`;
-/**
- * The Gateway's default chat model as a client: a base URL, a fetch and
- * the model name to send. Throws `ConfigurationError` where
- * `createGatewayFetch` does (no binding and no dev key) and
- * `AttributionError` where a shared app's call says nobody's.
- */
 export function ai(options) {
+    const fetch = createGatewayFetch(options);
+    if (!fetch)
+        return null;
     return {
         baseURL: AI_DEFAULT_BASE_URL,
-        fetch: createGatewayFetch(options),
+        fetch,
         model: AI_DEFAULT_MODEL,
         chatCompletionsUrl: `${AI_DEFAULT_BASE_URL}/chat/completions`,
         embeddingsUrl: `${AI_DEFAULT_BASE_URL}/embeddings`,
     };
 }
+const CHAT_COMPLETIONS = "/chat/completions";
+/**
+ * A provider's root behind the Gateway, `http://every-app-gateway.internal/api/ai/<provider>`:
+ * join the provider's own paths onto it (`/api/v1/chat/completions` for
+ * OpenRouter) and send them with `createGatewayFetch()`. For an OpenAI
+ * client's `baseURL`, use {@link aiBaseUrl}.
+ */
+export function providerBaseUrl(provider) {
+    return `${BINDING_ORIGIN}/api/ai/${encodeURIComponent(provider)}`;
+}
+/**
+ * The OpenAI-compatible base URL of `provider` behind the Gateway, for an
+ * OpenAI client's `baseURL` (with `fetch: createGatewayFetch(...)`):
+ * `default` (the default) is {@link AI_DEFAULT_BASE_URL},
+ * `…/api/ai/default/v1`; a catalog provider's is its root and the prefix
+ * of its chat route (`…/api/ai/openrouter/api/v1`, `…/api/ai/workers-ai/v1`,
+ * `…/api/ai/openai/v1`). Throws `ConfigurationError` for a provider with
+ * no OpenAI-compatible chat route (Cohere): call {@link providerBaseUrl}
+ * with its own paths instead.
+ */
+export function aiBaseUrl(provider = AI_DEFAULT_PROVIDER) {
+    if (provider === AI_DEFAULT_PROVIDER)
+        return AI_DEFAULT_BASE_URL;
+    const capability = CATALOG.get(provider);
+    const chat = capability?.mode === "ai" && "chat" in capability
+        ? capability.chat
+        : undefined;
+    if (!chat?.path.endsWith(CHAT_COMPLETIONS)) {
+        throw new ConfigurationError(`${provider} has no OpenAI-compatible chat route in the catalog: join its own paths onto providerBaseUrl("${provider}") instead.`);
+    }
+    return `${providerBaseUrl(provider)}${chat.path.slice(0, -CHAT_COMPLETIONS.length)}`;
+}

package/dist/server/aiBinding.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `gatewayAiBinding(env)`: the Gateway's AI providers as a Workers AI
+ * binding, for code written against `env.AI.run(model, inputs, options)`.
+ *
+ * An app on Every App needs no `ai` binding of its own to call models: the
+ * Gateway holds the keys, counts the calls and keeps the app to `ai.models`.
+ * Code that already calls `env.AI.run()` (upstream code a port keeps, the
+ * Agents SDK, `workers-ai-provider`) gets this object in its place:
+ *
+ *   const AI = gatewayAiBinding(env, { for: request });
+ *   await AI.run("@cf/meta/llama-3.1-8b-instruct-fast", { messages });
+ *
+ * Each `run()` becomes an OpenAI-compatible call on the provider's route
+ * through the Gateway (`createGatewayFetch`): text generation (`messages`
+ * or `prompt`) on its chat completions route, text embeddings (`text`) on
+ * its embeddings route, answered in Workers AI's shapes (`{ response,
+ * tool_calls, usage }`, `{ shape, data }`, or a stream of `data:
+ * {"response": …}` events with `stream: true`). In local development
+ * without a Gateway, the developer's own key in `.dev.vars` is used, as
+ * `createGatewayFetch` does (WORKERS_AI_API_TOKEN and CLOUDFLARE_ACCOUNT_ID
+ * for Workers AI).
+ */
+import { AI_DEFAULT_PROVIDER, type AiProviderId } from "../internal/index.js";
+import type { GatewayCallFor } from "./attribution.js";
+export interface GatewayAiBindingOptions {
+    /**
+     * Whom the calls are for: the inbound request, or `{ background: true,
+     * organizationId }` (createGatewayFetch's `for`).
+     */
+    for?: GatewayCallFor;
+    /**
+     * The Gateway provider the calls go to: an `ai` entry of the catalog
+     * with OpenAI-compatible routes (`workers-ai`, `openrouter`, `openai`,
+     * …), or `default`, the operator's model (`ai: { chat: true }`).
+     * Default: `workers-ai`, the provider `env.AI` reaches, so `@cf/…` model
+     * ids work as they are. The manifest lists the provider under
+     * `providers` (or says `ai.chat` for `default`).
+     */
+    provider?: AiProviderId | typeof AI_DEFAULT_PROVIDER;
+    /**
+     * The model id to send for a model the code names, e.g.
+     * `{ "@cf/meta/llama-3.1-8b-instruct-fast": "meta-llama/llama-3.1-8b-instruct" }`
+     * with `provider: "openrouter"`. A model not listed is sent as it is,
+     * except that on `default` an `@cf/…` id becomes `default` (the
+     * operator's model).
+     */
+    models?: Readonly<Record<string, string>>;
+}
+/**
+ * A Workers AI binding (`Ai`) over the Gateway: pass it where code takes
+ * `env.AI`. `run()` covers text generation (messages or prompt; tools;
+ * `stream: true`; `returnRawResponse`, which returns the provider's
+ * OpenAI-shaped `Response`) and text embeddings; the binding's other
+ * methods (`gateway()`, `autorag()`, `models()`, `toMarkdown()`, …) and
+ * other tasks (images, audio, batches, websockets) throw
+ * `ConfigurationError`. `options.gateway` is ignored: the Gateway's
+ * operator decides whether calls go through Cloudflare AI Gateway
+ * (`everyapp ai gateway on`).
+ *
+ * Errors are thrown as a binding throws them: `GatewayRefusalError` when
+ * the Gateway refused (`ai_provider_not_configured`, `model_not_allowed`,
+ * …), `ConfigurationError` where createGatewayFetch throws one (no binding
+ * and no dev key), and an `Error` naming the status when the provider
+ * answered with an error. Nothing is checked when the binding is made, so
+ * making one per request costs nothing.
+ */
+export declare function gatewayAiBinding(env: object, options?: GatewayAiBindingOptions): Ai;
+//# sourceMappingURL=aiBinding.d.ts.map

package/dist/server/aiBinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aiBinding.d.ts","sourceRoot":"","sources":["../../src/server/aiBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAEL,mBAAmB,EAInB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQvD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,mBAAmB,CAAC;IACrD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3C;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,EAAE,CAoEJ"}