@north-light/sdk 0.3.632 → 0.3.633

package/dist/resources/inference-endpoint.d.ts

@@ -36,7 +36,7 @@ export interface InferenceEndpointOptions {
     baseURL: string;
     /** The app's own principal, `app:<id>`; it prefixes the vendor reference of a call the vendor gave no request id. */
     app: string;
-    /** The app's Anthropic API key. It is used only for a call the directory admits as card-paid (no `pool` in the admission), and is never logged or returned. */
+    /** The app's Anthropic API key. It serves a call the directory admits as card-paid (no `pool` in the admission) and a Northlight-paid call the pool could not serve (see `inferenceEndpoint`). It is never logged or returned. */
     apiKey: string;
     /** Strength to model: `anthropic/<model id>` for each rung the endpoint serves. A request naming any other model is refused. Every model needs a list price in this SDK; the constructor throws for one that has none. */
     rungs: Partial<Record<InferenceRung, string>>;
@@ -60,9 +60,15 @@ export interface InferenceEndpointOptions {
  * directory's `payment` body, and a directory that cannot be reached or answers anything unexpected is 503 with nothing sent upstream.
  *
  * The upstream comes from the admission answer. An answer carrying `pool` (Northlight pays) sends the call to the pool at
- * `pool.url` with `pool.token`, and the call settles at list price with `cost_usd` 0. An answer without it (the person pays) sends
- * the call to Anthropic with the app's `apiKey`, and `cost_usd` equals the list price. There is no other route: an unreachable or
- * refusing pool answers the caller 502 or the pool's own status (a 429 keeps its `Retry-After`) and never reaches the API key.
+ * `pool.url` with `pool.token`, and a call the pool serves settles at list price with `cost_usd` 0. An answer without it (the person
+ * pays) sends the call to Anthropic with the app's `apiKey`, and `cost_usd` equals the list price.
+ *
+ * When the pool cannot serve a Northlight-paid call, the same request is sent to Anthropic with `apiKey` instead of being refused.
+ * That happens when the pool is unreachable or answers 401, 402, 403, 404, 408, 429 or any 5xx (every login rate-limited, no login,
+ * a pool-side refusal, a pool failure). Any other pool answer, notably a 400 for a malformed request, goes back to the caller
+ * unchanged, because the key would fail the same way. A call the key serves settles under the same admission with `cost_usd` equal
+ * to the list price (Northlight paid real money for it), so the directory counts it as it counts a pool call, and the log entry
+ * says `upstream: 'api_key_fallback'` with the pool's status. If the key's attempt fails too, its answer (or a 502) reaches the caller.
  *
  * The answer streams back with `Crtr-Charge-Id` and calculated `crtr_charge` on its terminal event (or JSON body), without waiting
  * for settlement. Usage is read off the stream and reported to the directory at the list price of the model the vendor reports it

package/dist/resources/inference-endpoint.js

@@ -9,6 +9,9 @@ const DIRECTORY_TIMEOUT_MS = 10_000;
 /** Posts made in the request's own lifetime before the stored report is left to `sweep`. */
 const IMMEDIATE_ATTEMPTS = 3;
 const SWEEP_BATCH = 50;
+/** Pool answers the API key could plausibly serve instead: the pool or its login is unavailable or refused the call (401, 402, 403, 404 no login, 408), every login is rate-limited (429), or the pool failed (5xx). Any other status, 400 above all, would fail the same way at Anthropic and reaches the caller. */
+const POOL_FALLBACK_STATUSES = new Set([401, 402, 403, 404, 408, 429]);
+const poolFallbackStatus = (status) => POOL_FALLBACK_STATUSES.has(status) || status >= 500;
 const STRIPPED_REQUEST_HEADERS = ['host', 'connection', 'keep-alive', 'transfer-encoding', 'te', 'upgrade', 'content-length', 'authorization', 'x-api-key', 'cookie', 'proxy-authorization'];
 // The body is decoded and re-streamed, so these describe the upstream wire form, not what we send.
 const STRIPPED_RESPONSE_HEADERS = ['connection', 'keep-alive', 'transfer-encoding', 'content-encoding', 'content-length'];
@@ -150,9 +153,15 @@ function chargedBody(body, contentType, charge) {
  * directory's `payment` body, and a directory that cannot be reached or answers anything unexpected is 503 with nothing sent upstream.
  *
  * The upstream comes from the admission answer. An answer carrying `pool` (Northlight pays) sends the call to the pool at
- * `pool.url` with `pool.token`, and the call settles at list price with `cost_usd` 0. An answer without it (the person pays) sends
- * the call to Anthropic with the app's `apiKey`, and `cost_usd` equals the list price. There is no other route: an unreachable or
- * refusing pool answers the caller 502 or the pool's own status (a 429 keeps its `Retry-After`) and never reaches the API key.
+ * `pool.url` with `pool.token`, and a call the pool serves settles at list price with `cost_usd` 0. An answer without it (the person
+ * pays) sends the call to Anthropic with the app's `apiKey`, and `cost_usd` equals the list price.
+ *
+ * When the pool cannot serve a Northlight-paid call, the same request is sent to Anthropic with `apiKey` instead of being refused.
+ * That happens when the pool is unreachable or answers 401, 402, 403, 404, 408, 429 or any 5xx (every login rate-limited, no login,
+ * a pool-side refusal, a pool failure). Any other pool answer, notably a 400 for a malformed request, goes back to the caller
+ * unchanged, because the key would fail the same way. A call the key serves settles under the same admission with `cost_usd` equal
+ * to the list price (Northlight paid real money for it), so the directory counts it as it counts a pool call, and the log entry
+ * says `upstream: 'api_key_fallback'` with the pool's status. If the key's attempt fails too, its answer (or a 502) reaches the caller.
  *
  * The answer streams back with `Crtr-Charge-Id` and calculated `crtr_charge` on its terminal event (or JSON body), without waiting
  * for settlement. Usage is read off the stream and reported to the directory at the list price of the model the vendor reports it
@@ -207,7 +216,7 @@ export function inferenceEndpoint(options) {
             if (pool === undefined)
                 return { kind: 'admitted', admissionId: admission_id, chargeId: charge_id, pool: undefined };
             const { url, token: poolToken } = object(pool) ?? {};
-            // A pool the helper cannot read is not an admission for the API key.
+            // An admission whose pool the helper cannot read is malformed, so the call is not served.
             return typeof url === 'string' && url !== '' && typeof poolToken === 'string' && poolToken !== ''
                 ? { kind: 'admitted', admissionId: admission_id, chargeId: charge_id, pool: { url: url.replace(/\/+$/, ''), token: poolToken } }
                 : { kind: 'unavailable' };
@@ -307,22 +316,47 @@ export function inferenceEndpoint(options) {
             return refuse(403, 'permission_error', admission.message);
         if (admission.kind === 'unavailable')
             return refuse(503, 'admission_unavailable', 'Northlight could not confirm payment for this call. Try again shortly.');
-        const headers = new Headers(request.headers);
+        const baseHeaders = new Headers(request.headers);
         for (const name of STRIPPED_REQUEST_HEADERS)
-            headers.delete(name);
-        const pool = admission.pool;
-        if (pool !== undefined)
+            baseHeaders.delete(name);
+        // Not tied to the caller's connection: the vendor bills the whole answer, so the usage branch reads it to its end and the settlement is complete.
+        const sendToPool = (pool) => {
+            const headers = new Headers(baseHeaders);
             headers.set('authorization', `Bearer ${pool.token}`);
-        else
+            return upstreamFetch(`${pool.url}/${POOL_MESSAGES_PATH}`, { method: 'POST', headers, body, redirect: 'manual' });
+        };
+        const sendToVendor = () => {
+            const headers = new Headers(baseHeaders);
             headers.set('x-api-key', options.apiKey);
-        const upstreamUrl = pool !== undefined ? `${pool.url}/${POOL_MESSAGES_PATH}` : `${VENDOR_URL}/${MESSAGES_PATH}`;
+            return upstreamFetch(`${VENDOR_URL}/${MESSAGES_PATH}`, { method: 'POST', headers, body, redirect: 'manual' });
+        };
         let answer;
-        try {
-            // Not tied to the caller's connection: the vendor bills the whole answer, so the usage branch reads it to its end and the settlement is complete.
-            answer = await upstreamFetch(upstreamUrl, { method: 'POST', headers, body, redirect: 'manual' });
+        let upstream = admission.pool !== undefined ? 'pool' : 'api_key';
+        if (admission.pool !== undefined) {
+            let poolFailure;
+            try {
+                answer = await sendToPool(admission.pool);
+                if (poolFallbackStatus(answer.status)) {
+                    poolFailure = String(answer.status);
+                    void answer.body?.cancel().catch(() => undefined);
+                    answer = undefined;
+                }
+            }
+            catch (error) {
+                poolFailure = String(error);
+            }
+            if (poolFailure !== undefined) {
+                upstream = 'api_key_fallback';
+                log({ sub, model, admission: admission.admissionId, upstream, pool_failed: poolFailure });
+            }
         }
-        catch {
-            return refuse(502, 'upstream_unreachable', `${pool !== undefined ? 'The Claude pool' : 'anthropic'} could not be reached.`);
+        if (answer === undefined) {
+            try {
+                answer = await sendToVendor();
+            }
+            catch {
+                return refuse(502, 'upstream_unreachable', `${upstream === 'api_key_fallback' ? 'The Claude pool and anthropic' : 'anthropic'} could not be reached.`);
+            }
         }
         const responseHeaders = new Headers(answer.headers);
         for (const name of STRIPPED_RESPONSE_HEADERS)
@@ -365,7 +399,7 @@ export function inferenceEndpoint(options) {
                 served_model: servedModel,
                 units,
                 list_usd: list,
-                cost_usd: pool !== undefined ? 0 : list,
+                cost_usd: upstream === 'pool' ? 0 : list,
                 vendor_ref: vendorRef,
             };
             return { settlement, usage };
@@ -375,7 +409,7 @@ export function inferenceEndpoint(options) {
                 return;
             const { settlement, usage } = result;
             await record(settlement);
-            log({ sub, model, served_model: settlement.served_model, admission: admission.admissionId, upstream: pool !== undefined ? 'pool' : 'api_key', list_usd: settlement.list_usd, cost_usd: settlement.cost_usd, usage });
+            log({ sub, model, served_model: settlement.served_model, admission: admission.admissionId, upstream, list_usd: settlement.list_usd, cost_usd: settlement.cost_usd, usage });
         }).catch((error) => { log({ sub, admission: admission.admissionId, settle_failed: String(error) }); });
         const charge = calculated.then((result) => result === undefined ? undefined : { id: admission.chargeId, served_model: result.settlement.served_model, list_usd: result.settlement.list_usd }, () => undefined);
         return new Response(chargedBody(toCaller, contentType, charge), { status: answer.status, statusText: answer.statusText, headers: responseHeaders });

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.632"
+  sdk-version: "0.3.633"
 ---
 
 # Building a Northlight app
@@ -27,7 +27,7 @@ Never text a person first: Comms refuses a send to anyone who has not texted you
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.632`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.633`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.632";
+export declare const SDK_VERSION = "0.3.633";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.632';
+export const SDK_VERSION = '0.3.633';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.632",
+  "version": "0.3.633",
   "crouterContract": "1.51",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
@@ -44,9 +44,9 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.632",
-    "@north-light/identity": "0.3.632",
-    "@north-light/plugin": "0.3.632",
+    "@north-light/api": "0.3.633",
+    "@north-light/identity": "0.3.633",
+    "@north-light/plugin": "0.3.633",
     "jose": "^6.2.1"
   },
   "peerDependencies": {