@forgezero/providers 0.1.0 → 0.1.2

package/README.md

@@ -67,9 +67,9 @@ vendor you turned off is not a vendor that is failing.
 | `/pool` | which outbound address a request leaves by, sticky per key |
 | `/storage` | S3-compatible object storage, SigV4 signed with Web Crypto, no vendor SDK |
 
-Full documentation: **https://forgezero.net/docs/providers**
+Full documentation: **https://www.forgezero.net/docs/providers**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/binance.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));

package/dist/database.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/database.ts
 var pools = new Map;

package/dist/email.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];

package/dist/http.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/index.d.ts

@@ -152,4 +152,4 @@ export interface EmailMessage {
     from?: string;
     replyTo?: string;
 }
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";

package/dist/index.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 export {
   staticConfig,
   nextHealth,

package/dist/pool.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.js

@@ -125,7 +125,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/storage.ts
 var encoder = new TextEncoder;

package/dist/translation.d.ts

@@ -0,0 +1,70 @@
+import { defineProvider } from './index';
+/**
+ * Machine translation, as a service with providers behind it.
+ *
+ * ForgeZero does not translate anything at runtime — its own catalogues are
+ * filled in out of band, before a build. This exists because a TENANT may want
+ * it, and the alternative is every tenant writing the same retry, pacing and
+ * quota handling against whichever vendor they already pay for.
+ *
+ * Nothing here is specific to Google beyond the one adapter at the bottom. The
+ * service contract is "given source text and a target language, return the
+ * translated strings in order", and a tenant that prefers a different vendor
+ * writes forty lines rather than adopting ours.
+ *
+ * ## Why order matters in the contract
+ *
+ * Returning a map keyed by source string looks friendlier and loses duplicates:
+ * two identical English strings in different contexts are two entries in a
+ * catalogue and must stay two. Positional results keep them distinct.
+ */
+export interface TranslateRequest {
+    /** Source strings, in catalogue order. Duplicates are meaningful. */
+    texts: readonly string[];
+    /** BCP-47 code the texts are written in. */
+    from: string;
+    /** BCP-47 code to translate into. */
+    to: string;
+    /**
+     * What the strings are for, passed to the model as context.
+     *
+     * "Sign in" is a button in one product and an instruction in another, and a
+     * translator with no context picks wrong in exactly the places a user
+     * notices.
+     */
+    context?: string;
+}
+export interface TranslateResult {
+    /** One entry per input, in the same order. */
+    texts: string[];
+    /** What actually served the request, for a log somebody has to read later. */
+    model?: string;
+}
+/** Anything that can translate. A tenant may supply their own. */
+export type TranslationProvider = ReturnType<typeof defineProvider<TranslateRequest, TranslateResult>>;
+/**
+ * Google AI Studio, on the free tier.
+ *
+ * Chosen as the first adapter because the free tier is generous enough for a
+ * catalogue and needs no billing account — a tenant can try the feature without
+ * a procurement conversation.
+ *
+ * Structured output is requested explicitly. Asking a model for "JSON" in prose
+ * and parsing whatever comes back is how translation pipelines start returning
+ * markdown fences on a Tuesday; a schema makes the shape the model's problem.
+ */
+export declare const googleAiStudio: import("./index").ProviderSpec<TranslateRequest, TranslateResult>;
+export declare class TranslationError extends Error {
+    readonly code: 'NO_CREDENTIAL' | 'RATE_LIMITED' | 'REQUEST_FAILED' | 'EMPTY_RESPONSE' | 'LENGTH_MISMATCH';
+    readonly status?: number | undefined;
+    constructor(code: 'NO_CREDENTIAL' | 'RATE_LIMITED' | 'REQUEST_FAILED' | 'EMPTY_RESPONSE' | 'LENGTH_MISMATCH', message: string, status?: number | undefined);
+}
+/**
+ * Read an array of strings out of a model response.
+ *
+ * Fences are stripped defensively: models that honour `responseSchema` never
+ * emit them, and models that ignore it wrap the same JSON in ```json. Handling
+ * both costs three lines and removes a class of "worked until we changed model".
+ */
+export declare function parseStrings(raw: string): string[];
+export declare const translationProviders: readonly [import("./index").ProviderSpec<TranslateRequest, TranslateResult>];

package/dist/translation.js

@@ -0,0 +1,244 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function staticConfig(services) {
+  const health = new Map;
+  return {
+    name: "static",
+    async list(serviceKey) {
+      return (services[serviceKey] ?? []).map((provider) => ({
+        ...provider,
+        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+      }));
+    },
+    async recordHealth(serviceKey, providerId, next) {
+      health.set(`${serviceKey}:${providerId}`, next);
+    }
+  };
+}
+function defineProvider(spec) {
+  return spec;
+}
+var STRIKES_TO_OFFLINE = 3;
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, args) {
+    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+    const attempts = [];
+    for (const entry of configured) {
+      const spec = byId.get(entry.providerId);
+      if (!spec) {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+        continue;
+      }
+      if (entry.health?.status === "offline") {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      options.before?.({ service: serviceKey, provider: entry.providerId });
+      try {
+        const result = await spec.invoke({
+          config: entry.config,
+          secret: (field) => options.credentials.get(entry.secretRef, field)
+        }, args);
+        attempts.push({ providerId: entry.providerId, outcome: "sent" });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, "success"));
+        const sent = { ok: true, result, provider: entry.providerId, attempts };
+        options.after?.(sent);
+        return sent;
+      } catch (error) {
+        const kind = spec.classify(error);
+        attempts.push({
+          providerId: entry.providerId,
+          outcome: "failed",
+          kind,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider is configured for "${serviceKey}".` : `Every provider for "${serviceKey}" failed or was skipped.`)
+    };
+    options.after?.(failed);
+    return failed;
+  }
+  return { call };
+}
+var VERSION = "0.1.2";
+
+// src/translation.ts
+var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";
+var googleAiStudio = defineProvider({
+  id: "google-ai-studio",
+  service: "translation",
+  label: "Google AI Studio",
+  credentials: {
+    type: "object",
+    required: ["apiKey"],
+    properties: {
+      apiKey: {
+        type: "string",
+        title: "API key",
+        writeOnly: true,
+        description: "From aistudio.google.com. The free tier is enough for a catalogue."
+      }
+    }
+  },
+  config: {
+    type: "object",
+    properties: {
+      model: {
+        type: "string",
+        title: "Model",
+        default: "gemini-2.0-flash",
+        description: "Any model this key can reach. Flash tiers are fastest and cheapest."
+      }
+    }
+  },
+  async invoke(context, args) {
+    const apiKey = await context.secret("apiKey");
+    if (!apiKey)
+      throw new TranslationError("NO_CREDENTIAL", "No API key is configured.");
+    const model = String(context.config?.model ?? "gemini-2.0-flash");
+    const response = await fetch(`${GOOGLE_ENDPOINT}/${model}:generateContent`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-goog-api-key": apiKey },
+      signal: context.signal,
+      body: JSON.stringify({
+        contents: [
+          {
+            parts: [
+              {
+                text: [
+                  `Translate each string from ${args.from} to ${args.to}.`,
+                  args.context ? `They appear in: ${args.context}.` : "",
+                  "Return exactly one translation per input, in the same order.",
+                  "Preserve placeholders such as {0} or {name} exactly as written.",
+                  "Translate nothing that is a placeholder, a URL, or a code identifier.",
+                  "",
+                  JSON.stringify(args.texts)
+                ].filter(Boolean).join(`
+`)
+              }
+            ]
+          }
+        ],
+        generationConfig: {
+          responseMimeType: "application/json",
+          responseSchema: {
+            type: "ARRAY",
+            items: { type: "STRING" }
+          }
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new TranslationError(response.status === 429 ? "RATE_LIMITED" : "REQUEST_FAILED", `Google AI Studio answered ${response.status}.`, response.status);
+    }
+    const payload = await response.json();
+    const raw = payload.candidates?.[0]?.content?.parts?.[0]?.text;
+    if (!raw)
+      throw new TranslationError("EMPTY_RESPONSE", "The model returned nothing.");
+    const texts = parseStrings(raw);
+    if (texts.length !== args.texts.length) {
+      throw new TranslationError("LENGTH_MISMATCH", `Asked for ${args.texts.length} translations and received ${texts.length}.`);
+    }
+    return { texts, model };
+  },
+  classify(error) {
+    if (error instanceof TranslationError) {
+      if (error.code === "RATE_LIMITED")
+        return "backoff";
+      if (error.code === "NO_CREDENTIAL" || error.code === "LENGTH_MISMATCH")
+        return "terminal";
+    }
+    return "retryable";
+  }
+});
+
+class TranslationError extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "TranslationError";
+  }
+}
+function parseStrings(raw) {
+  const cleaned = raw.trim().replace(/^```(?:json)?/i, "").replace(/```$/, "").trim();
+  const parsed = JSON.parse(cleaned);
+  if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) {
+    throw new TranslationError("EMPTY_RESPONSE", "The model did not return a list of strings.");
+  }
+  return parsed;
+}
+var translationProviders = [googleAiStudio];
+export {
+  translationProviders,
+  parseStrings,
+  googleAiStudio,
+  TranslationError
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
   "name": "@forgezero/providers",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -38,11 +38,15 @@
     "./binance": {
       "types": "./dist/binance.d.ts",
       "default": "./dist/binance.js"
+    },
+    "./translation": {
+      "types": "./dist/translation.d.ts",
+      "default": "./dist/translation.js"
     }
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "build": "bun build src/index.ts src/email.ts src/chain.ts src/database.ts src/http.ts src/pool.ts src/storage.ts src/binance.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+    "build": "bun build src/index.ts src/email.ts src/chain.ts src/database.ts src/http.ts src/pool.ts src/storage.ts src/binance.ts src/translation.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
     "prepublishOnly": "bun run check && bun run build"
   },
   "devDependencies": {
@@ -62,13 +66,13 @@
     "object-storage"
   ],
   "license": "MIT",
-  "homepage": "https://forgezero.net/docs/providers",
+  "homepage": "https://www.forgezero.net/docs/providers",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/axxra/forgezero.git",
+    "url": "git+https://github.com/forgezero-net/packages.git",
     "directory": "packages/providers"
   },
-  "bugs": "https://github.com/axxra/forgezero/issues",
+  "bugs": "https://github.com/forgezero-net/packages/issues",
   "sideEffects": false,
   "types": "./dist/index.d.ts",
   "files": [
@@ -77,6 +81,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgezero/runtime": "^0.1.0"
+    "@forgezero/runtime": "^0.1.2"
   }
 }