@volter/twin-fireworks 0.1.0

package/dist/src/fireworks-connector.d.ts

@@ -0,0 +1,168 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { FireworksBudget, fireworksBudgetPath, type FireworksBudgetOptions } from './fireworks-budget.js';
+/** The account every Gateway REST path is addressed under when no caller (or subject namespace)
+ *  supplies one. The vendor keys every control-plane path by account id; the twin models one
+ *  default account, and the perform path derives the account from the SUBJECT's own namespace
+ *  first, falling back to this constant only for a bare id. */
+export declare const FIREWORKS_ACCOUNT_ID = "my-account";
+/**
+ * The injected real-Fireworks boundary. `request` issues ONE Fireworks REST call against either
+ * plane:
+ *   method — 'GET' | 'POST' | 'PATCH' | 'DELETE'
+ *   path   — e.g. '/inference/v1/chat/completions' or
+ *            '/v1/accounts/{account_id}/deployments?deploymentId=my-deployment'
+ *   body   — JSON body for POST/PATCH (omitted otherwise)
+ * Returns the parsed JSON envelope (an OpenAI-compat completion, a gateway list envelope, or an
+ * error shape).
+ */
+export type FireworksExecute = (method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<{
+    status: number;
+    data: unknown;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveFireworksOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: FireworksBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: FireworksBudgetOptions;
+};
+/**
+ * A live executor against the real Fireworks API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.fireworks.ai` request, and therefore the one
+ * place the rate budget is enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `FireworksBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 becomes a persisted cooldown that makes every later call fail fast WITHOUT
+ * touching Fireworks. There is deliberately no OPTION to disable the guard, and no value a caller
+ * can pass for `budget` that yields an unguarded client. What that does NOT claim is immunity from
+ * a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected clock,
+ * restores the allowance, because the same seam tests need cannot be denied to a determined caller
+ * in the same process. See `fireworks-budget.ts` and the kernel header for the limits of the
+ * guarantee.
+ */
+export declare function liveFireworksExecute(apiKey: string, base?: string, opts?: LiveFireworksOptions): FireworksExecute;
+/** Map one gateway deployment row → a twin sync resource. Vendor `name` is
+ *  `accounts/{account}/deployments/{id}`; the twin keys the resource by the id segment. */
+export declare function mapDeployment(d: Record<string, unknown>): SyncResource;
+export declare function mapDataset(ds: Record<string, unknown>): SyncResource;
+export declare function mapBatchInferenceJob(j: Record<string, unknown>): SyncResource;
+export declare function mapSupervisedFineTuningJob(j: Record<string, unknown>): SyncResource;
+export declare function mapUser(u: Record<string, unknown>): SyncResource;
+export declare function mapModel(m: Record<string, unknown>): SyncResource;
+/** Secrets never carry their value on a list read (the vendor redacts it), so the map stores the
+ *  metadata only — mirroring the vendor's own read surface. */
+export declare function mapSecret(s: Record<string, unknown>): SyncResource;
+/** Fetch the account's control-plane state through the injected client and map to SyncResource[]
+ *  (no fold). `accountId` scopes every list; a missing/failed list throws — a REFUSED pull is NOT
+ *  an empty account, and folding an empty list over real observed state would tombstone it. */
+export declare function pullFireworksState(execute: FireworksExecute, accountId: string): Promise<SyncResource[]>;
+/**
+ * D7 consumer-facing pull entry point: gather all Fireworks control-plane read domains and fold
+ * them into the twin through a SINGLE observed batch, returning the standard result shape.
+ * Idempotent: a re-pull of identical state appends no new deltas.
+ */
+export declare function syncFireworksFromReal(execute: FireworksExecute, opts?: {
+    accountId: string;
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** Why this operation cannot be pushed to the real vendor, or null if it can. Pure — no vendor
+ *  call on its path. Inference operations are the big class: replaying a completion at the vendor
+ *  spends real money and stores nothing, so a push of one is a category error, not a gap. */
+export declare function unpushableReason(op: string): string | null;
+/**
+ * The REST (method, path, body) that CONFIRMS one local action against the real Gateway REST
+ * surface. Create ids go where the vendor's spec puts them (query params for deployments/users,
+ * the body for the rest). A locally-minted id on anything but a create is REFUSED — the twin's
+ * own mint is not an address the vendor knows.
+ */
+export declare function fireworksRequestForAction(action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, accountId: string, opts?: {
+    externalId?: string;
+}): {
+    method: 'POST' | 'DELETE';
+    path: string;
+    body?: Record<string, unknown>;
+};
+/**
+ * Push ONE pending action to REAL Fireworks via the injected executor. Returns the real external
+ * id (the vendor's own id from the create response's `name`, or the addressed id on delete).
+ * WRITES TO THE REAL ACCOUNT.
+ */
+export declare function pushFireworksAction(execute: FireworksExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, accountId: string, opts?: {
+    externalId?: string;
+}): Promise<{
+    externalId: string;
+}>;
+/**
+ * Push the twin's PENDING local actions to real Fireworks and CONFIRM each. Idempotent: a
+ * confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed and
+ * never silently dropped: it stays pending and is named in `refused`. A create's real id is
+ * recorded on the resource as `_external_id` at confirm time, so a later delete addresses the
+ * VENDOR by it — never the twin's own mint.
+ */
+export declare function pushPendingFireworksActions(execute: FireworksExecute, opts: {
+    accountId: string;
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * Fireworks and confirm it, then (2) PULL the control-plane collections back and fold them into
+ * the event log. Pushing first means the pull observes the twin's own writes as confirmed external
+ * state (no double-count). Re-running with no pending writes and identical real state is a no-op.
+ */
+export declare function fullSyncFireworks(execute: FireworksExecute, opts: {
+    accountId: string;
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pushed: number;
+    observed: number;
+    deltasAppended: number;
+    collections: number;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;
+/** A `FireworksExecute` over the kernel's executor — the adapter seam protocol 2 fixes. */
+export declare function fireworksExecuteOver(execute: RemoteExecute): FireworksExecute;
+/** The refresh adapter: pull the account's control-plane collections. `origin` is unused —
+ *  Fireworks' surface is single-host, so the executor's own base URL is the address. */
+export declare function syncFireworksFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    accountId?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter — the head's executor for a local write at a REAL boundary. Create/delete
+ * replay against the Gateway REST surface through `ctx.resolve` (a locally minted subject is
+ * addressed by the vendor id the projection recorded, never by the mint). Inference operations and
+ * custom verbs are NOT performed: they are the twin's own record, and the outcome says so.
+ */
+export declare function performFireworksAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+export { fireworksBudgetPath };