@myapihq/sdk 2.0.1 → 2.1.0

package/dist/funds.d.ts

@@ -0,0 +1,11 @@
+import { MyApiError } from './client';
+export type AutoRechargeState = 'in_flight' | 'disabled' | 'capped' | 'no_pm' | 'failed';
+export declare function isInsufficientFunds(err: unknown): err is MyApiError;
+export declare function isSpendCapExceeded(err: unknown): err is MyApiError;
+export declare function autoRechargeState(err: unknown): AutoRechargeState | undefined;
+export interface FundsRetryOptions {
+    maxRetries?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onRetry?: (attempt: number, waitSeconds: number) => void;
+}
+export declare function withFundsRetry<T>(call: () => Promise<T>, opts?: FundsRetryOptions): Promise<T>;

package/dist/funds.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInsufficientFunds = isInsufficientFunds;
+exports.isSpendCapExceeded = isSpendCapExceeded;
+exports.autoRechargeState = autoRechargeState;
+exports.withFundsRetry = withFundsRetry;
+const client_1 = require("./client");
+// Wallet empty. Matches the unified `INSUFFICIENT_FUNDS` and the legacy
+// `INSUFFICIENT_BALANCE` (still emitted by imagegen's free-tier path until the
+// backend finishes the split — tolerate both).
+function isInsufficientFunds(err) {
+    return err instanceof client_1.MyApiError &&
+        (err.code === 'INSUFFICIENT_FUNDS' || err.code === 'INSUFFICIENT_BALANCE');
+}
+// Hard account spend ceiling hit (distinct from an empty wallet). Always needs
+// a human — raising/clearing the cap — never a retry or top-up.
+function isSpendCapExceeded(err) {
+    return err instanceof client_1.MyApiError && err.code === 'SPEND_CAP_EXCEEDED';
+}
+// The auto_recharge state on an INSUFFICIENT_FUNDS error, if the backend set it.
+function autoRechargeState(err) {
+    if (!(err instanceof client_1.MyApiError))
+        return undefined;
+    const s = err.body?.auto_recharge;
+    return typeof s === 'string' ? s : undefined;
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Wrap a billable call so an empty wallet with an auto-recharge IN FLIGHT is
+// polled-and-retried instead of failing — the whole point of the 402 split,
+// so an autonomous agent doesn't escalate to a human for a refill that's
+// already coming. Retries ONLY on `INSUFFICIENT_FUNDS` + `auto_recharge ===
+// 'in_flight'`, sleeping the server-provided `retry_after_seconds` (fallback
+// 5s), up to maxRetries. Every other case — capped / no_pm / failed /
+// disabled, or a `SPEND_CAP_EXCEEDED` hard ceiling — rethrows immediately:
+// those need a human (top up, fix the card, raise the cap), not a retry.
+async function withFundsRetry(call, opts = {}) {
+    const maxRetries = opts.maxRetries ?? 3;
+    const sleep = opts.sleep ?? defaultSleep;
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (attempt >= maxRetries || !isInsufficientFunds(err) || autoRechargeState(err) !== 'in_flight') {
+                throw err;
+            }
+            attempt++;
+            const hinted = err.body?.retry_after_seconds;
+            const waitSec = typeof hinted === 'number' && hinted > 0 ? hinted : 5;
+            opts.onRetry?.(attempt, waitSec);
+            await sleep(waitSec * 1000);
+        }
+    }
+}

package/dist/hq.d.ts

@@ -138,6 +138,26 @@ export declare function setupPayment(apiKey: string): Promise<{
 export declare function topUp(apiKey: string, amountDollars: number): Promise<{
     new_balance_display: string;
 }>;
+export type RechargeStatus = 'succeeded' | 'failed' | 'capped' | 'no_pm' | 'pending';
+export interface AutoRechargeConfig {
+    enabled: boolean;
+    threshold_cents: number | null;
+    amount_cents: number | null;
+    monthly_cap_cents: number | null;
+    month_to_date_recharged_cents: number;
+    has_payment_method: boolean;
+    last_recharge_status: RechargeStatus | null;
+    last_recharge_attempt_at: string | null;
+}
+export declare function getAutoRecharge(apiKey: string): Promise<AutoRechargeConfig>;
+export interface SetAutoRechargeInput {
+    enabled: boolean;
+    threshold_cents?: number;
+    amount_cents?: number;
+    monthly_cap_cents?: number;
+}
+export declare function setAutoRecharge(apiKey: string, input: SetAutoRechargeInput): Promise<AutoRechargeConfig>;
+export declare function disableAutoRecharge(apiKey: string): Promise<void>;
 export type DoctorSeverity = 'ok' | 'warn' | 'crit';
 export interface DoctorEntityRef {
     slot: string;
@@ -152,11 +172,13 @@ export interface DoctorIssue {
     category?: string;
     message: string;
     hint?: string;
+    operator_only?: boolean;
 }
 export interface DoctorSection {
     name: string;
     summary: string;
     issues: DoctorIssue[];
+    resource_count?: number;
 }
 export interface DoctorReport {
     org_id: string;

package/dist/hq.js

@@ -27,6 +27,9 @@ exports.getBillingHistory = getBillingHistory;
 exports.getBillingUsage = getBillingUsage;
 exports.setupPayment = setupPayment;
 exports.topUp = topUp;
+exports.getAutoRecharge = getAutoRecharge;
+exports.setAutoRecharge = setAutoRecharge;
+exports.disableAutoRecharge = disableAutoRecharge;
 exports.getDoctor = getDoctor;
 const client_1 = require("./client");
 const config_1 = require("./config");
@@ -170,6 +173,21 @@ async function setupPayment(apiKey) {
 async function topUp(apiKey, amountDollars) {
     return (0, client_1.request)('POST', `${config_1.HQ_BASE}/hq/billing/topup`, apiKey, { amount_dollars: amountDollars });
 }
+async function getAutoRecharge(apiKey) {
+    return (0, client_1.request)('GET', `${config_1.HQ_BASE}/hq/billing/auto-recharge`, apiKey);
+}
+// Enable/update auto-recharge. The backend validates invariants and rejects
+// with a 400 (`MISSING_FIELDS`, `AMOUNT_BELOW_FLOOR` [$5 floor],
+// `AMOUNT_LT_THRESHOLD`, `CAP_LT_AMOUNT`, `NO_PAYMENT_METHOD`) — surfaced as a
+// MyApiError. Returns the full config on success.
+async function setAutoRecharge(apiKey, input) {
+    return (0, client_1.request)('PUT', `${config_1.HQ_BASE}/hq/billing/auto-recharge`, apiKey, input);
+}
+// Disable auto-recharge (the threshold/amount/cap are preserved for easy
+// re-enable). Backend returns 204 No Content.
+async function disableAutoRecharge(apiKey) {
+    return (0, client_1.request)('DELETE', `${config_1.HQ_BASE}/hq/billing/auto-recharge`, apiKey);
+}
 async function getDoctor(apiKey, orgId) {
     return (0, client_1.request)('GET', `${config_1.HQ_BASE}/hq/orgs/${encodeURIComponent(orgId)}/doctor`, apiKey);
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './client';
+export * from './funds';
 export * as hq from './hq';
 export * as auth from './auth';
 export * as domain from './domain';

package/dist/index.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.task = exports.queue = exports.git = exports.container = exports.payments = exports.fn = exports.crm = exports.database = exports.llm = exports.audience = exports.company = exports.people = exports.url = exports.workflow = exports.webhook = exports.storage = exports.pixel = exports.image = exports.funnel = exports.email = exports.domain = exports.auth = exports.hq = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./funds"), exports);
 // Note: config constants (STORAGE_BASE etc.) are NOT re-exported from the
 // barrel. TypeScript compiles `export * from './config'` to a runtime
 // `__exportStar` call that Node's cjs-module-lexer can't see through, so

package/dist/services.js

@@ -48,8 +48,8 @@ exports.SERVICES = [
     },
     // ── send ────────────────────────────────────────────────────────────
     {
-        // Customer-facing email surface — mailboxes, campaigns, templates,
-        // warmup. Launched 2026-05-17: the backend lifted the pre-launch gate
+        // Customer-facing email surface — mailboxes, transactional send,
+        // templates, warmup. Launched 2026-05-17: the backend lifted the pre-launch gate
         // (the [disabled, pre-launch] / 503 SERVICE_NOT_LAUNCHED state is gone).
         // Sibling `my-email-verify-api` is the sync single-address verifier.
         module: 'email',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/sdk",
   "license": "Apache-2.0",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "TypeScript SDK for the MyAPI ecosystem",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/funds.ts

@@ -0,0 +1,66 @@
+import { MyApiError } from './client';
+
+// The auto-recharge state the backend carries on an `INSUFFICIENT_FUNDS` 402.
+// `in_flight` = a refill was triggered and is on its way (retry); everything
+// else needs a human action, not a retry.
+export type AutoRechargeState = 'in_flight' | 'disabled' | 'capped' | 'no_pm' | 'failed';
+
+// Wallet empty. Matches the unified `INSUFFICIENT_FUNDS` and the legacy
+// `INSUFFICIENT_BALANCE` (still emitted by imagegen's free-tier path until the
+// backend finishes the split — tolerate both).
+export function isInsufficientFunds(err: unknown): err is MyApiError {
+  return err instanceof MyApiError &&
+    (err.code === 'INSUFFICIENT_FUNDS' || err.code === 'INSUFFICIENT_BALANCE');
+}
+
+// Hard account spend ceiling hit (distinct from an empty wallet). Always needs
+// a human — raising/clearing the cap — never a retry or top-up.
+export function isSpendCapExceeded(err: unknown): err is MyApiError {
+  return err instanceof MyApiError && err.code === 'SPEND_CAP_EXCEEDED';
+}
+
+// The auto_recharge state on an INSUFFICIENT_FUNDS error, if the backend set it.
+export function autoRechargeState(err: unknown): AutoRechargeState | undefined {
+  if (!(err instanceof MyApiError)) return undefined;
+  const s = err.body?.auto_recharge;
+  return typeof s === 'string' ? (s as AutoRechargeState) : undefined;
+}
+
+export interface FundsRetryOptions {
+  // Max poll-and-retry attempts on an in-flight refill (default 3).
+  maxRetries?: number;
+  // Injectable sleep (tests pass a no-op; default is real setTimeout).
+  sleep?: (ms: number) => Promise<void>;
+  // Called before each wait — e.g. to log "balance low, refill in flight…".
+  onRetry?: (attempt: number, waitSeconds: number) => void;
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+// Wrap a billable call so an empty wallet with an auto-recharge IN FLIGHT is
+// polled-and-retried instead of failing — the whole point of the 402 split,
+// so an autonomous agent doesn't escalate to a human for a refill that's
+// already coming. Retries ONLY on `INSUFFICIENT_FUNDS` + `auto_recharge ===
+// 'in_flight'`, sleeping the server-provided `retry_after_seconds` (fallback
+// 5s), up to maxRetries. Every other case — capped / no_pm / failed /
+// disabled, or a `SPEND_CAP_EXCEEDED` hard ceiling — rethrows immediately:
+// those need a human (top up, fix the card, raise the cap), not a retry.
+export async function withFundsRetry<T>(call: () => Promise<T>, opts: FundsRetryOptions = {}): Promise<T> {
+  const maxRetries = opts.maxRetries ?? 3;
+  const sleep = opts.sleep ?? defaultSleep;
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await call();
+    } catch (err) {
+      if (attempt >= maxRetries || !isInsufficientFunds(err) || autoRechargeState(err) !== 'in_flight') {
+        throw err;
+      }
+      attempt++;
+      const hinted = (err as MyApiError).body?.retry_after_seconds;
+      const waitSec = typeof hinted === 'number' && hinted > 0 ? hinted : 5;
+      opts.onRetry?.(attempt, waitSec);
+      await sleep(waitSec * 1000);
+    }
+  }
+}

package/src/hq.ts

@@ -281,6 +281,51 @@ export async function topUp(apiKey: string, amountDollars: number): Promise<{ ne
   return request('POST', `${BASE_URL}/hq/billing/topup`, apiKey, { amount_dollars: amountDollars });
 }
 
+// ── Auto-recharge ──────────────────────────────────────────────────────
+// Keeps the prepaid wallet funded without a human in the loop: when the
+// balance drops below `threshold_cents`, the backend charges the saved card
+// `amount_cents` off-session, bounded by `monthly_cap_cents`. Opt-in, off by
+// default; enabling requires a saved payment method.
+
+export type RechargeStatus = 'succeeded' | 'failed' | 'capped' | 'no_pm' | 'pending';
+
+export interface AutoRechargeConfig {
+  enabled: boolean;
+  threshold_cents: number | null;
+  amount_cents: number | null;
+  monthly_cap_cents: number | null;
+  // Auto-recharge dollars charged this calendar month (vs the cap).
+  month_to_date_recharged_cents: number;
+  has_payment_method: boolean;
+  last_recharge_status: RechargeStatus | null;
+  last_recharge_attempt_at: string | null;
+}
+
+export async function getAutoRecharge(apiKey: string): Promise<AutoRechargeConfig> {
+  return request('GET', `${BASE_URL}/hq/billing/auto-recharge`, apiKey);
+}
+
+export interface SetAutoRechargeInput {
+  enabled: boolean;
+  threshold_cents?: number;
+  amount_cents?: number;
+  monthly_cap_cents?: number;
+}
+
+// Enable/update auto-recharge. The backend validates invariants and rejects
+// with a 400 (`MISSING_FIELDS`, `AMOUNT_BELOW_FLOOR` [$5 floor],
+// `AMOUNT_LT_THRESHOLD`, `CAP_LT_AMOUNT`, `NO_PAYMENT_METHOD`) — surfaced as a
+// MyApiError. Returns the full config on success.
+export async function setAutoRecharge(apiKey: string, input: SetAutoRechargeInput): Promise<AutoRechargeConfig> {
+  return request('PUT', `${BASE_URL}/hq/billing/auto-recharge`, apiKey, input);
+}
+
+// Disable auto-recharge (the threshold/amount/cap are preserved for easy
+// re-enable). Backend returns 204 No Content.
+export async function disableAutoRecharge(apiKey: string): Promise<void> {
+  return request('DELETE', `${BASE_URL}/hq/billing/auto-recharge`, apiKey);
+}
+
 // ── Org doctor ─────────────────────────────────────────────────────────
 // Aggregated consistency report across slots. The endpoint resolves the
 // reported org from the API key's binding, so the `{org_id}` path param
@@ -310,12 +355,26 @@ export interface DoctorIssue {
   category?: string;
   message: string;
   hint?: string;
+  // True when the issue is platform-side and NOT actionable by the customer
+  // (e.g. a degraded internal dependency the MyAPI team owns). The backend
+  // sets this together with `category: 'internal'` and a customer-appropriate
+  // message; the operator detail is routed to an internal sink, not here.
+  // Consumers should surface these for transparency but must NOT count them
+  // as customer-actionable failures (they don't fail `doctor`'s exit code).
+  operator_only?: boolean;
 }
 
 export interface DoctorSection {
   name: string;
   summary: string;
   issues: DoctorIssue[];
+  // Authoritative count of resources of this section's kind in the org,
+  // independent of how many issues were emitted. Lets a consumer tell
+  // "zero resources" apart from "resources present, all healthy" without
+  // inferring it from `issues.length` (which breaks the moment the backend
+  // stops emitting an `ok` row per healthy resource). Optional: older
+  // backends omit it, and consumers must fall back to the issue-count proxy.
+  resource_count?: number;
 }
 
 export interface DoctorReport {

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './client';
+export * from './funds';
 // Note: config constants (STORAGE_BASE etc.) are NOT re-exported from the
 // barrel. TypeScript compiles `export * from './config'` to a runtime
 // `__exportStar` call that Node's cjs-module-lexer can't see through, so

package/src/services.ts

@@ -75,8 +75,8 @@ export const SERVICES: readonly ServiceMeta[] = [
 
   // ── send ────────────────────────────────────────────────────────────
   {
-    // Customer-facing email surface — mailboxes, campaigns, templates,
-    // warmup. Launched 2026-05-17: the backend lifted the pre-launch gate
+    // Customer-facing email surface — mailboxes, transactional send,
+    // templates, warmup. Launched 2026-05-17: the backend lifted the pre-launch gate
     // (the [disabled, pre-launch] / 503 SERVICE_NOT_LAUNCHED state is gone).
     // Sibling `my-email-verify-api` is the sync single-address verifier.
     module: 'email',