@north-light/api 0.3.540 → 0.3.542

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.28";
+export declare const CONTRACT_LEVEL = "1.29";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.28';
+export const CONTRACT_LEVEL = '1.29';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/core/subscription-state.d.ts

@@ -77,18 +77,24 @@ export declare class DuplicateSubscriptionError extends Error {
     constructor(message: string);
 }
 export declare function readSubscriptionPool(provider: ManagedProviderId): SubscriptionCredential[];
+/** The pool with each account's row id: the stable handle a caller outside the process removes an account by. */
+export declare function readSubscriptionPoolRows(provider: ManagedProviderId): Array<{
+    id: string;
+    entry: SubscriptionCredential;
+}>;
 export declare function writeSubscriptionPool(provider: ManagedProviderId, next: SubscriptionCredential[]): Promise<SubscriptionCredential[]>;
 export declare function addSubscription(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
 export declare function upsertSubscription(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
 export declare function upsertSubscriptionWithUniqueAccount(provider: ManagedProviderId, entry: SubscriptionCredential): Promise<SubscriptionCredential[]>;
 export declare function renameSubscription(provider: ManagedProviderId, ref: string, nextLabel: string): Promise<SubscriptionCredential[]>;
 export declare function removeManagedAccount(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
+/** Remove the account whose row id is `id` (see `readSubscriptionPoolRows`); throws when no account has it. */
+export declare function removeManagedAccountById(provider: ManagedProviderId, id: string): Promise<SubscriptionCredential[]>;
 export declare function removeSubscription(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
 export declare function removeAllManagedAccounts(provider: ManagedProviderId): Promise<number>;
 export declare function removeManagedProvider(provider: ManagedProviderId, label?: string): Promise<SubscriptionCredential[]>;
 export declare function promoteSubscription(provider: ManagedProviderId, ref: string): Promise<SubscriptionCredential[]>;
 export declare function markSubscriptionAttempt(provider: ManagedProviderId, ref: string, attemptAt?: number): Promise<SubscriptionCredential[]>;
-export declare function markSubscriptionAuthenticationFailed(provider: ManagedProviderId, ref: string, attempted: Pick<SubscriptionCredential, 'refresh' | 'access'>, retryAfterMs: number, attemptAt?: number): Promise<SubscriptionCredential[]>;
 /** Record a 429 on an account. `scope` defaults to the whole account; a model scope cools only that family on this account, and a 429 older than the newest one already recorded for the same scope is ignored. */
 export declare function markSubscriptionRateLimited(provider: ManagedProviderId, ref: string, retryAfterMs: number, attemptAt?: number, rateLimitedAt?: number, scope?: RateLimitScope): Promise<SubscriptionCredential[]>;
 /** A call on `modelId` succeeded: clear the account-wide cooldown and auth failure, and that model family's cooldown, unless a newer 429 for the same scope landed after `attemptAt` began. */

package/dist/core/subscription-state.js

@@ -87,6 +87,8 @@ export class DuplicateSubscriptionError extends Error {
     constructor(message) { super(message); this.name = 'DuplicateSubscriptionError'; }
 }
 export function readSubscriptionPool(provider) { return rowsWithCredentials(provider, readFile(provider)).map(({ entry }) => entry); }
+/** The pool with each account's row id: the stable handle a caller outside the process removes an account by. */
+export function readSubscriptionPoolRows(provider) { return rowsWithCredentials(provider, readFile(provider)).map(({ row, entry }) => ({ id: row.id, entry })); }
 async function locked(provider, run) { const path = credentialFile(provider); return managedCredentialFile(provider).withLockAsync(async (current, _held, publish) => { const file = parseCredentials(path, current); return { result: await run(file, rowsWithCredentials(provider, file), (next) => publish(`${JSON.stringify(next)}\n`)) }; }); }
 function insert(db, provider, row) { cachedStatement(db, 'INSERT INTO managed_accounts(provider_id,id,label,label_key,position,last_attempt_at,last_rate_limited_at,rate_limited_until,auth_failure) VALUES(?,?,?,?,?,?,?,?,?)').run(provider, row.id, row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null); }
 function update(db, row) { cachedStatement(db, 'UPDATE managed_accounts SET label=?,label_key=?,position=?,last_attempt_at=?,last_rate_limited_at=?,rate_limited_until=?,auth_failure=? WHERE provider_id=? AND id=?').run(row.label, row.labelKey, row.position, row.lastAttemptAt, row.lastRateLimitedAt, row.rateLimitedUntil, row.authFailure ?? null, row.providerId, row.id); }
@@ -130,7 +132,7 @@ export async function upsertSubscriptionWithUniqueAccount(provider, entry) {
         const cooldownIncoming = checked.lastRateLimitedAt >= row.lastRateLimitedAt;
         file.accounts[row.id] = stored(checked);
         publish(file);
-        writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => { update(db, { ...row, label: checked.label, labelKey: key(checked.label), lastAttemptAt: Math.max(row.lastAttemptAt, checked.lastAttemptAt), lastRateLimitedAt: cooldownIncoming ? checked.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: cooldownIncoming ? checked.rateLimitedUntil : row.rateLimitedUntil }); if (differentAccount(existing.entry, checked))
+        writeMembershipAfterCredentialPublish(provider, () => providerWrite(agentDir(), (db) => { update(db, { ...row, authFailure: undefined, label: checked.label, labelKey: key(checked.label), lastAttemptAt: Math.max(row.lastAttemptAt, checked.lastAttemptAt), lastRateLimitedAt: cooldownIncoming ? checked.lastRateLimitedAt : row.lastRateLimitedAt, rateLimitedUntil: cooldownIncoming ? checked.rateLimitedUntil : row.rateLimitedUntil }); if (differentAccount(existing.entry, checked))
             deleteModelCooldowns(db, provider, row.id); }));
         return publicPool(provider, file);
     });
@@ -139,25 +141,24 @@ export async function renameSubscription(provider, ref, nextLabel) { return lock
     throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const label = nextLabel.trim(); if (!label)
     throw new Error(`${getProviderLabel(provider)} subscription label cannot be empty`); if (rows.some((value, i) => i !== index && key(value.entry.label) === key(label)))
     throw new DuplicateSubscriptionError(`${getProviderLabel(provider)} subscription already exists: ${label}`); providerWrite(agentDir(), (db) => update(db, { ...rows[index].row, label, labelKey: key(label) })); return publicPool(provider, file); }); }
-async function remove(provider, ref) { return locked(provider, async (file, rows, publish) => { const index = resolve(rows, ref); if (index < 0)
-    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const removed = rows[index].row; providerWrite(agentDir(), (db) => { cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=? AND id=?').run(provider, removed.id); deleteModelCooldowns(db, provider, removed.id); }); delete file.accounts[removed.id]; publish(file); return publicPool(provider, file); }); }
-export async function removeManagedAccount(provider, ref) { return remove(provider, ref); }
-export async function removeSubscription(provider, ref) { return remove(provider, ref); }
+async function remove(provider, find, missing) { return locked(provider, async (file, rows, publish) => { const index = find(rows); if (index < 0)
+    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${missing}`); const removed = rows[index].row; providerWrite(agentDir(), (db) => { cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=? AND id=?').run(provider, removed.id); deleteModelCooldowns(db, provider, removed.id); }); delete file.accounts[removed.id]; publish(file); return publicPool(provider, file); }); }
+export async function removeManagedAccount(provider, ref) { return remove(provider, (rows) => resolve(rows, ref), ref); }
+/** Remove the account whose row id is `id` (see `readSubscriptionPoolRows`); throws when no account has it. */
+export async function removeManagedAccountById(provider, id) { return remove(provider, (rows) => rows.findIndex(({ row }) => row.id === id), id); }
+export async function removeSubscription(provider, ref) { return remove(provider, (rows) => resolve(rows, ref), ref); }
 export async function removeAllManagedAccounts(provider) { return locked(provider, async (file, rows, publish) => { providerWrite(agentDir(), (db) => { cachedStatement(db, 'DELETE FROM managed_accounts WHERE provider_id=?').run(provider); deleteModelCooldowns(db, provider); }); for (const { row } of rows)
     delete file.accounts[row.id]; publish(file); return rows.length; }); }
 export async function removeManagedProvider(provider, label) { if (label === undefined) {
     await removeAllManagedAccounts(provider);
     return [];
-} return remove(provider, label); }
+} return removeManagedAccount(provider, label); }
 export async function promoteSubscription(provider, ref) { return locked(provider, async (file, rows) => { const index = resolve(rows, ref); if (index < 0)
     throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); providerWrite(agentDir(), (db) => { const reordered = [rows[index], ...rows.filter((_, i) => i !== index)]; reordered.forEach((item, position) => update(db, { ...item.row, position })); }); return publicPool(provider, file); }); }
 async function mutateHealth(provider, ref, mutate) { providerWrite(agentDir(), (db) => { const row = providerRowByReference(db, provider, ref); if (!row)
     throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); const next = mutate(row); if (next)
     update(db, next); }); return readSubscriptionPool(provider); }
 export async function markSubscriptionAttempt(provider, ref, attemptAt = Date.now()) { return mutateHealth(provider, ref, (row) => ({ ...row, lastAttemptAt: Math.max(row.lastAttemptAt, attemptAt) })); }
-export async function markSubscriptionAuthenticationFailed(provider, ref, attempted, retryAfterMs, attemptAt = Date.now()) { return locked(provider, async (file, rows) => { const current = rows.find(({ entry }) => key(entry.label) === key(ref)); if (!current)
-    throw new Error(`Unknown ${getProviderLabel(provider)} subscription: ${ref}`); if (current.entry.refresh !== attempted.refresh || current.entry.access !== attempted.access)
-    return publicPool(provider, file); providerWrite(agentDir(), (db) => update(db, { ...current.row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(current.row.lastAttemptAt, attemptAt), rateLimitedUntil: Math.max(current.row.rateLimitedUntil, attemptAt + Math.max(0, retryAfterMs)) })); return publicPool(provider, file); }); }
 /** Record a 429 on an account. `scope` defaults to the whole account; a model scope cools only that family on this account, and a 429 older than the newest one already recorded for the same scope is ignored. */
 export async function markSubscriptionRateLimited(provider, ref, retryAfterMs, attemptAt = Date.now(), rateLimitedAt = Date.now(), scope = { kind: 'account' }) {
     retryAfterMs = Math.min(Math.max(0, retryAfterMs), MAX_RATE_LIMIT_COOLDOWN_MS);
@@ -192,9 +193,18 @@ export async function markSubscriptionSuccess(provider, ref, attemptAt = Date.no
     });
     return readSubscriptionPool(provider);
 }
+/** The vendor refused this account's refresh token: flag the row so every pool reader skips it until a sign-in replaces it. Both refresh paths (pi's `modify` and the daemon's /v1/llm) record it here. */
+function recordInvalidGrant(row) { const at = Date.now(); providerWrite(agentDir(), (db) => update(db, { ...row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(row.lastAttemptAt, at), rateLimitedUntil: Math.max(row.rateLimitedUntil, at + INVALID_REFRESH_TOKEN_BACKOFF_MS) })); }
 export async function refreshSubscriptionCredential(provider, label, exchange) { return locked(provider, async (file, rows, publish) => { const index = resolve(rows, label); if (index < 0)
     throw new Error(`${getProviderLabel(provider)} subscription "${label}" no longer exists`); const current = rows[index]; if (current.entry.expires > Date.now())
-    return current.entry; const next = await exchange(current.entry.refresh, current.entry.clientId); const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId); file.accounts[current.row.id] = { ...file.accounts[current.row.id], ...tokens }; publish(file); return { ...current.entry, ...tokens }; }); }
+    return current.entry; let next; try {
+    next = await exchange(current.entry.refresh, current.entry.clientId);
+}
+catch (error) {
+    if (isInvalidRefreshTokenError(error))
+        recordInvalidGrant(current.row);
+    throw error;
+} const tokens = withClientId(assertTokens(provider, current.entry.label, next), next.clientId ?? current.entry.clientId); file.accounts[current.row.id] = { ...file.accounts[current.row.id], ...tokens }; publish(file); return { ...current.entry, ...tokens }; }); }
 export function isInvalidRefreshTokenError(error) { const value = error; const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : ''].filter((part) => typeof part === 'string').join(' '); const status = typeof value?.status === 'number' ? value.status : Number(message.match(/\bstatus[=:]\s*(\d+)/i)?.[1]); return status === 400 && /invalid_grant|refresh token .*invalid|refresh token .*not found/i.test(message); }
 export async function modifyElectedSubscription(provider, elect, apply) { return locked(provider, async (file, rows, publish) => { const attempted = new Set(); let lastError; while (attempted.size < rows.length) {
     const chosen = elect(rows.filter(({ entry }) => !attempted.has(entry.label)).map(({ entry }) => entry));
@@ -216,8 +226,7 @@ export async function modifyElectedSubscription(provider, elect, apply) { return
         if (!isInvalidRefreshTokenError(error))
             throw error;
         lastError = error;
-        const at = Date.now();
-        providerWrite(agentDir(), (db) => update(db, { ...current.row, authFailure: 'invalid_grant', lastAttemptAt: Math.max(current.row.lastAttemptAt, at), rateLimitedUntil: Math.max(current.row.rateLimitedUntil, at + INVALID_REFRESH_TOKEN_BACKOFF_MS) }));
+        recordInvalidGrant(current.row);
     }
 } if (lastError)
     throw lastError; return undefined; }); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.540",
+  "version": "0.3.542",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",