@tabai/sdk 0.2.0

package/dist/payments/registry.js

@@ -0,0 +1,199 @@
+/**
+ * Strategy registration and resolution: mechanisms one and two of R23.6.
+ *
+ * One implementation serves both. A registry is a keyed set of strategies with an
+ * optional parent it falls back to:
+ *
+ * - **Constructor injection.** `createStrategyRegistry({ strategies: [...] })`
+ *   is what a client wrapper builds from its own options, so a consumer passes
+ *   strategies in and never touches global state. Its parent is the module-level
+ *   registry by default, so injection adds to what is already registered instead
+ *   of hiding it.
+ * - **The module-level registry.** `registerPaymentStrategy(strategy)` writes to
+ *   one process-wide registry, which is what a plugin package needs: it
+ *   self-registers on import and the consumer's only line is the import.
+ *
+ * ## Why the module-level state hangs off `globalThis`
+ *
+ * A plugin package that self-registers on import may resolve a *different copy*
+ * of `@tabai/sdk` than the application does, different versions, a nested
+ * `node_modules`, a bundled duplicate. With module-scoped state each copy gets
+ * its own registry, the plugin registers into a registry the application never
+ * reads, and the failure is silent: the strategy simply never resolves. So the
+ * state lives under a versioned `Symbol.for` key on `globalThis` and every copy
+ * of this module wraps the same `Map`. Only the shared state is global; the
+ * behaviour is each copy's own.
+ *
+ * ## Idempotence, and what replacement means
+ *
+ * `register` is keyed by `strategy.id`:
+ *
+ * - the same object again is a no-op, `unchanged`, no warning, no reordering;
+ * - a *different* object under a live id replaces it **in its original
+ *   position** and warns through the logger rather than throwing (design section
+ *   9.3), because a strategy replaced at the back of the queue would silently
+ *   change which strategy resolves for every other Asset too;
+ * - anything else appends.
+ *
+ * Order matters because resolution order is registration order, so the operation
+ * has to be idempotent in the ordering as well as in the membership. `Map.set`
+ * on a live key keeps the key's insertion position, which is exactly this rule.
+ *
+ * ## Resolution order
+ *
+ * An explicit `strategyId` wins. Otherwise the first strategy whose
+ * `supports(asset)` returns true, in registration order, own entries before the
+ * parent's (design section 9.3). A named strategy that does not support the Asset
+ * is an error rather than a silent fall-through to another one: a caller that
+ * named a strategy meant it.
+ *
+ * Requirements: 23.6, 21.5
+ */
+import { ok } from "../_shared/index.js";
+import { defaultLogger } from "../logger.js";
+import { notFoundError, validationError } from "../errors.js";
+import { assetKey, supportsAsset, validatePaymentStrategy, } from "./strategy.js";
+/** Versioned so a future state-shape change cannot be misread by an older copy. */
+const MODULE_STATE_KEY = Symbol.for("@tabai/sdk.paymentStrategies.v1");
+function moduleState() {
+    const host = globalThis;
+    const existing = host[MODULE_STATE_KEY];
+    if (existing !== undefined && existing.version === 1)
+        return existing;
+    const created = { version: 1, strategies: new Map() };
+    host[MODULE_STATE_KEY] = created;
+    return created;
+}
+/**
+ * Builds a registry.
+ *
+ * Construction cannot fail, so it does not return a `Result`. An invalid entry in
+ * `strategies` is refused and reported through the logger, and the registry comes
+ * back holding the valid ones, a consumer's typo in one strategy should not take
+ * out the strategies that were fine. Use {@link StrategyRegistry.register}
+ * directly when the caller wants the `Result` for each one.
+ */
+export function createStrategyRegistry(options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const own = new Map();
+    const registry = registryOver(own, logger, () => resolveParent(options.inherit));
+    for (const strategy of options.strategies ?? []) {
+        const outcome = registry.register(strategy);
+        if (!outcome.ok) {
+            logger.error("payment strategy rejected at construction", {
+                code: outcome.error.code,
+                message: outcome.error.message,
+            });
+        }
+    }
+    return registry;
+}
+/** The process-wide registry mechanism two writes to. */
+export function moduleStrategyRegistry(logger) {
+    return registryOver(moduleState().strategies, logger ?? defaultLogger, () => undefined);
+}
+/**
+ * Registers a strategy process-wide. Idempotent by `strategy.id`.
+ *
+ * This is the whole of mechanism two: a plugin package calls it at import time,
+ * and the consumer's only line is `import "@acme/tab-strategy-solana"`.
+ */
+export function registerPaymentStrategy(strategy, options = {}) {
+    return moduleStrategyRegistry(options.logger).register(strategy);
+}
+/** Removes a process-wide registration. Returns false when the id was not registered. */
+export const unregisterPaymentStrategy = (id) => moduleStrategyRegistry().unregister(id);
+/** Every process-wide registration, in registration order. */
+export const listPaymentStrategies = () => moduleStrategyRegistry().list();
+/** Empties the process-wide registry. Present for hosts that rebuild their world. */
+export const clearPaymentStrategies = () => moduleStrategyRegistry().clear();
+/** Resolves against the process-wide registry alone. */
+export const resolvePaymentStrategy = (query) => moduleStrategyRegistry().resolve(query);
+function resolveParent(inherit) {
+    if (inherit === false)
+        return undefined;
+    if (inherit !== undefined)
+        return inherit;
+    return moduleStrategyRegistry();
+}
+/**
+ * The one registry implementation, over a `Map` it does not own.
+ *
+ * `parent` is a thunk so the module-level registry can be the default parent
+ * without this function forcing it into existence at construction time, which
+ * would make the load order of two modules matter.
+ */
+function registryOver(own, logger, parent) {
+    const registry = {
+        register(candidate) {
+            const validated = validatePaymentStrategy(candidate);
+            if (!validated.ok)
+                return validated;
+            const strategy = validated.value;
+            const previous = own.get(strategy.id);
+            if (previous === strategy) {
+                return ok({ action: "unchanged", strategy });
+            }
+            if (previous !== undefined) {
+                // Map.set keeps the key's original insertion position, so the replacement
+                // inherits the displaced strategy's place in the resolution order.
+                own.set(strategy.id, strategy);
+                logger.warn("payment strategy replaced an earlier registration of the same id", {
+                    strategyId: strategy.id,
+                    chainIds: strategy.chainIds.map((chainId) => chainId.toString(10)),
+                });
+                return ok({ action: "replaced", strategy, previous });
+            }
+            own.set(strategy.id, strategy);
+            return ok({ action: "registered", strategy });
+        },
+        unregister: (id) => own.delete(id),
+        clear: () => own.clear(),
+        list() {
+            const inherited = parent()?.list() ?? [];
+            const merged = [...own.values()];
+            for (const strategy of inherited) {
+                if (!own.has(strategy.id))
+                    merged.push(strategy);
+            }
+            return merged;
+        },
+        get(id) {
+            return own.get(id) ?? parent()?.get(id);
+        },
+        resolve(query) {
+            const candidates = registry.list();
+            const onThrow = (strategyId) => (error) => logger.warn("payment strategy supports() threw and was read as unsupported", {
+                strategyId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (query.strategyId !== undefined) {
+                const named = registry.get(query.strategyId);
+                if (named === undefined) {
+                    return notFoundError("STRATEGY_NOT_FOUND", `no payment strategy is registered under id \`${query.strategyId}\``, {
+                        details: {
+                            strategyId: query.strategyId,
+                            registered: candidates.map((strategy) => strategy.id).join(", "),
+                        },
+                    });
+                }
+                if (!supportsAsset(named, query.asset, onThrow(named.id))) {
+                    return validationError("STRATEGY_ASSET_MISMATCH", `payment strategy \`${named.id}\` does not support asset ${assetKey(query.asset)}`, { details: { strategyId: named.id, asset: assetKey(query.asset) } });
+                }
+                return ok(named);
+            }
+            for (const strategy of candidates) {
+                if (supportsAsset(strategy, query.asset, onThrow(strategy.id)))
+                    return ok(strategy);
+            }
+            return notFoundError("NO_STRATEGY_FOR_ASSET", `no registered payment strategy supports asset ${assetKey(query.asset)}`, {
+                details: {
+                    asset: assetKey(query.asset),
+                    registered: candidates.map((strategy) => strategy.id).join(", "),
+                },
+            });
+        },
+    };
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/payments/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/payments/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Strategy registration and resolution: mechanisms one and two of R23.6.\n *\n * One implementation serves both. A registry is a keyed set of strategies with an\n * optional parent it falls back to:\n *\n * - **Constructor injection.** `createStrategyRegistry({ strategies: [...] })`\n *   is what a client wrapper builds from its own options, so a consumer passes\n *   strategies in and never touches global state. Its parent is the module-level\n *   registry by default, so injection adds to what is already registered instead\n *   of hiding it.\n * - **The module-level registry.** `registerPaymentStrategy(strategy)` writes to\n *   one process-wide registry, which is what a plugin package needs: it\n *   self-registers on import and the consumer's only line is the import.\n *\n * ## Why the module-level state hangs off `globalThis`\n *\n * A plugin package that self-registers on import may resolve a *different copy*\n * of `@tabai/sdk` than the application does, different versions, a nested\n * `node_modules`, a bundled duplicate. With module-scoped state each copy gets\n * its own registry, the plugin registers into a registry the application never\n * reads, and the failure is silent: the strategy simply never resolves. So the\n * state lives under a versioned `Symbol.for` key on `globalThis` and every copy\n * of this module wraps the same `Map`. Only the shared state is global; the\n * behaviour is each copy's own.\n *\n * ## Idempotence, and what replacement means\n *\n * `register` is keyed by `strategy.id`:\n *\n * - the same object again is a no-op, `unchanged`, no warning, no reordering;\n * - a *different* object under a live id replaces it **in its original\n *   position** and warns through the logger rather than throwing (design section\n *   9.3), because a strategy replaced at the back of the queue would silently\n *   change which strategy resolves for every other Asset too;\n * - anything else appends.\n *\n * Order matters because resolution order is registration order, so the operation\n * has to be idempotent in the ordering as well as in the membership. `Map.set`\n * on a live key keeps the key's insertion position, which is exactly this rule.\n *\n * ## Resolution order\n *\n * An explicit `strategyId` wins. Otherwise the first strategy whose\n * `supports(asset)` returns true, in registration order, own entries before the\n * parent's (design section 9.3). A named strategy that does not support the Asset\n * is an error rather than a silent fall-through to another one: a caller that\n * named a strategy meant it.\n *\n * Requirements: 23.6, 21.5\n */\n\nimport { ok, type Result } from \"../_shared/index.js\";\nimport { defaultLogger, type Logger } from \"../logger.js\";\nimport { notFoundError, validationError } from \"../errors.js\";\nimport {\n  assetKey,\n  supportsAsset,\n  validatePaymentStrategy,\n  type AssetRef,\n  type PaymentStrategy,\n} from \"./strategy.js\";\n\n/** What `register` did. `unchanged` is the idempotent case. */\nexport type RegistrationAction = \"registered\" | \"replaced\" | \"unchanged\";\n\nexport interface StrategyRegistration {\n  readonly action: RegistrationAction;\n  readonly strategy: PaymentStrategy;\n  /** The strategy that was displaced, on `replaced` alone. */\n  readonly previous?: PaymentStrategy;\n}\n\n/** What resolution is given: the Asset that must be settled, and an optional override. */\nexport interface StrategyQuery {\n  readonly asset: AssetRef;\n  readonly strategyId?: string;\n}\n\nexport interface StrategyRegistry {\n  register(strategy: PaymentStrategy): Result<StrategyRegistration>;\n  /** Removes a strategy from *this* registry. Never reaches into the parent. */\n  unregister(id: string): boolean;\n  /** Empties *this* registry. Never reaches into the parent. */\n  clear(): void;\n  /** This registry's own strategies in registration order, then the parent's. */\n  list(): readonly PaymentStrategy[];\n  get(id: string): PaymentStrategy | undefined;\n  resolve(query: StrategyQuery): Result<PaymentStrategy>;\n}\n\nexport interface StrategyRegistryOptions {\n  /** Registered in array order at construction. Mechanism one. */\n  readonly strategies?: readonly PaymentStrategy[];\n  readonly logger?: Logger;\n  /**\n   * The registry to fall back to. Omitted means the module-level registry;\n   * `false` means an isolated registry, which is what the module-level registry\n   * itself is and what a test wants.\n   */\n  readonly inherit?: StrategyRegistry | false;\n}\n\n/** Versioned so a future state-shape change cannot be misread by an older copy. */\nconst MODULE_STATE_KEY = Symbol.for(\"@tabai/sdk.paymentStrategies.v1\");\n\ninterface ModuleState {\n  readonly version: 1;\n  readonly strategies: Map<string, PaymentStrategy>;\n}\n\nfunction moduleState(): ModuleState {\n  const host = globalThis as typeof globalThis & { [MODULE_STATE_KEY]?: ModuleState };\n  const existing = host[MODULE_STATE_KEY];\n  if (existing !== undefined && existing.version === 1) return existing;\n  const created: ModuleState = { version: 1, strategies: new Map() };\n  host[MODULE_STATE_KEY] = created;\n  return created;\n}\n\n/**\n * Builds a registry.\n *\n * Construction cannot fail, so it does not return a `Result`. An invalid entry in\n * `strategies` is refused and reported through the logger, and the registry comes\n * back holding the valid ones, a consumer's typo in one strategy should not take\n * out the strategies that were fine. Use {@link StrategyRegistry.register}\n * directly when the caller wants the `Result` for each one.\n */\nexport function createStrategyRegistry(options: StrategyRegistryOptions = {}): StrategyRegistry {\n  const logger = options.logger ?? defaultLogger;\n  const own = new Map<string, PaymentStrategy>();\n  const registry = registryOver(own, logger, () => resolveParent(options.inherit));\n\n  for (const strategy of options.strategies ?? []) {\n    const outcome = registry.register(strategy);\n    if (!outcome.ok) {\n      logger.error(\"payment strategy rejected at construction\", {\n        code: outcome.error.code,\n        message: outcome.error.message,\n      });\n    }\n  }\n  return registry;\n}\n\n/** The process-wide registry mechanism two writes to. */\nexport function moduleStrategyRegistry(logger?: Logger): StrategyRegistry {\n  return registryOver(moduleState().strategies, logger ?? defaultLogger, () => undefined);\n}\n\n/**\n * Registers a strategy process-wide. Idempotent by `strategy.id`.\n *\n * This is the whole of mechanism two: a plugin package calls it at import time,\n * and the consumer's only line is `import \"@acme/tab-strategy-solana\"`.\n */\nexport function registerPaymentStrategy(\n  strategy: PaymentStrategy,\n  options: { readonly logger?: Logger } = {},\n): Result<StrategyRegistration> {\n  return moduleStrategyRegistry(options.logger).register(strategy);\n}\n\n/** Removes a process-wide registration. Returns false when the id was not registered. */\nexport const unregisterPaymentStrategy = (id: string): boolean =>\n  moduleStrategyRegistry().unregister(id);\n\n/** Every process-wide registration, in registration order. */\nexport const listPaymentStrategies = (): readonly PaymentStrategy[] =>\n  moduleStrategyRegistry().list();\n\n/** Empties the process-wide registry. Present for hosts that rebuild their world. */\nexport const clearPaymentStrategies = (): void => moduleStrategyRegistry().clear();\n\n/** Resolves against the process-wide registry alone. */\nexport const resolvePaymentStrategy = (query: StrategyQuery): Result<PaymentStrategy> =>\n  moduleStrategyRegistry().resolve(query);\n\nfunction resolveParent(inherit: StrategyRegistry | false | undefined): StrategyRegistry | undefined {\n  if (inherit === false) return undefined;\n  if (inherit !== undefined) return inherit;\n  return moduleStrategyRegistry();\n}\n\n/**\n * The one registry implementation, over a `Map` it does not own.\n *\n * `parent` is a thunk so the module-level registry can be the default parent\n * without this function forcing it into existence at construction time, which\n * would make the load order of two modules matter.\n */\nfunction registryOver(\n  own: Map<string, PaymentStrategy>,\n  logger: Logger,\n  parent: () => StrategyRegistry | undefined,\n): StrategyRegistry {\n  const registry: StrategyRegistry = {\n    register(candidate) {\n      const validated = validatePaymentStrategy(candidate);\n      if (!validated.ok) return validated;\n      const strategy = validated.value;\n      const previous = own.get(strategy.id);\n\n      if (previous === strategy) {\n        return ok({ action: \"unchanged\", strategy });\n      }\n      if (previous !== undefined) {\n        // Map.set keeps the key's original insertion position, so the replacement\n        // inherits the displaced strategy's place in the resolution order.\n        own.set(strategy.id, strategy);\n        logger.warn(\"payment strategy replaced an earlier registration of the same id\", {\n          strategyId: strategy.id,\n          chainIds: strategy.chainIds.map((chainId) => chainId.toString(10)),\n        });\n        return ok({ action: \"replaced\", strategy, previous });\n      }\n      own.set(strategy.id, strategy);\n      return ok({ action: \"registered\", strategy });\n    },\n\n    unregister: (id) => own.delete(id),\n\n    clear: () => own.clear(),\n\n    list() {\n      const inherited = parent()?.list() ?? [];\n      const merged = [...own.values()];\n      for (const strategy of inherited) {\n        if (!own.has(strategy.id)) merged.push(strategy);\n      }\n      return merged;\n    },\n\n    get(id) {\n      return own.get(id) ?? parent()?.get(id);\n    },\n\n    resolve(query) {\n      const candidates = registry.list();\n      const onThrow = (strategyId: string) => (error: unknown) =>\n        logger.warn(\"payment strategy supports() threw and was read as unsupported\", {\n          strategyId,\n          error: error instanceof Error ? error.message : String(error),\n        });\n\n      if (query.strategyId !== undefined) {\n        const named = registry.get(query.strategyId);\n        if (named === undefined) {\n          return notFoundError(\n            \"STRATEGY_NOT_FOUND\",\n            `no payment strategy is registered under id \\`${query.strategyId}\\``,\n            {\n              details: {\n                strategyId: query.strategyId,\n                registered: candidates.map((strategy) => strategy.id).join(\", \"),\n              },\n            },\n          );\n        }\n        if (!supportsAsset(named, query.asset, onThrow(named.id))) {\n          return validationError(\n            \"STRATEGY_ASSET_MISMATCH\",\n            `payment strategy \\`${named.id}\\` does not support asset ${assetKey(query.asset)}`,\n            { details: { strategyId: named.id, asset: assetKey(query.asset) } },\n          );\n        }\n        return ok(named);\n      }\n\n      for (const strategy of candidates) {\n        if (supportsAsset(strategy, query.asset, onThrow(strategy.id))) return ok(strategy);\n      }\n      return notFoundError(\n        \"NO_STRATEGY_FOR_ASSET\",\n        `no registered payment strategy supports asset ${assetKey(query.asset)}`,\n        {\n          details: {\n            asset: assetKey(query.asset),\n            registered: candidates.map((strategy) => strategy.id).join(\", \"),\n          },\n        },\n      );\n    },\n  };\n\n  return registry;\n}\n"]}

package/dist/payments/strategy.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The payment-strategy seam.
+ *
+ * A strategy is how an Agent pays down an Open Tab. On Monad there is exactly one
+ * way: approve the Asset and call `TabSettlement.settle`, which moves the Asset to
+ * the Service and applies the Settlement in the same transaction. The seam still
+ * exists so that a different signer, a smart account, a session key, or a test
+ * double can stand behind the same call without the SDK caring which.
+ *
+ * ## What a strategy does not do
+ *
+ * It does not meter, it does not read tabs, and it does not decide amounts. It is
+ * handed a fully specified charge and returns either a receipt or a typed error.
+ * Every figure crossing this seam is a `bigint` count of Asset base units, never a
+ * number and never a decimal string.
+ */
+import { type Address, type Bytes32, type Hex, type Result } from "../_shared/index.js";
+/** One Asset a tab can be denominated in. `chainId` is the EVM chain id. */
+export interface AssetRef {
+    readonly chainId: bigint;
+    readonly address: Address;
+    readonly decimals: number;
+    readonly symbol: string;
+}
+/** What a Service is asking to be paid, before any strategy is chosen. */
+export interface ChargeRequest {
+    readonly agent: Address;
+    readonly serviceId: Bytes32;
+    readonly asset: AssetRef;
+    readonly amount: bigint;
+}
+/** A charge the strategy has been asked to pay. The surface resolves where the money goes. */
+export type SettleRequest = ChargeRequest;
+export interface ChargeQuote {
+    readonly amount: bigint;
+    readonly asset: AssetRef;
+    readonly feeNote: string;
+}
+/**
+ * What came back from a Settlement.
+ *
+ * `settlementId`, `applied` and `toPrepaid` are read from the `Settled` event in the
+ * transaction receipt. They are `null` only when the signer could not wait for the
+ * receipt, in which case the transaction hash still names the payment and the registry
+ * will carry the figures once it indexes the block.
+ */
+export interface SettlementReceipt {
+    readonly strategyId: string;
+    readonly chainId: bigint;
+    readonly txHash: Hex;
+    readonly asset: AssetRef;
+    readonly amount: bigint;
+    readonly payer: Address;
+    readonly serviceId: Bytes32;
+    readonly settlementId: Bytes32 | null;
+    readonly applied: bigint | null;
+    readonly toPrepaid: bigint | null;
+    readonly submittedAt: number;
+    readonly batchIndex?: number;
+}
+export interface PaymentStrategy {
+    readonly id: string;
+    /** The chain ids this strategy can settle on. */
+    readonly chainIds: readonly bigint[];
+    supports(asset: AssetRef): boolean;
+    quote(request: ChargeRequest): Promise<Result<ChargeQuote>>;
+    settle(request: SettleRequest): Promise<Result<SettlementReceipt>>;
+    settleBatch?(requests: readonly SettleRequest[]): Promise<Result<readonly SettlementReceipt[]>>;
+}
+/** The registry key for an Asset: `<chainId>:<address>`, lower-cased. */
+export declare const assetKey: (asset: AssetRef) => string;
+export declare const sameAsset: (a: AssetRef, b: AssetRef) => boolean;
+/** A 20-byte address as a 32-byte topic. */
+export declare const addressTopic: (address: Address) => Bytes32;
+export declare function supportsAsset(strategy: PaymentStrategy, asset: AssetRef, onThrow?: (error: unknown) => void): boolean;
+export declare function validateAssetRef(value: unknown, label: string): Result<AssetRef>;
+export declare function validatePaymentStrategy(value: unknown, label?: string): Result<PaymentStrategy>;
+export declare function validateChargeRequest(request: ChargeRequest): Result<ChargeRequest>;
+export declare const validateSettleRequest: typeof validateChargeRequest;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/payments/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/payments/strategy.ts"],"names":[],"mappings":"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"}

package/dist/payments/strategy.js

@@ -0,0 +1,103 @@
+/**
+ * The payment-strategy seam.
+ *
+ * A strategy is how an Agent pays down an Open Tab. On Monad there is exactly one
+ * way: approve the Asset and call `TabSettlement.settle`, which moves the Asset to
+ * the Service and applies the Settlement in the same transaction. The seam still
+ * exists so that a different signer, a smart account, a session key, or a test
+ * double can stand behind the same call without the SDK caring which.
+ *
+ * ## What a strategy does not do
+ *
+ * It does not meter, it does not read tabs, and it does not decide amounts. It is
+ * handed a fully specified charge and returns either a receipt or a typed error.
+ * Every figure crossing this seam is a `bigint` count of Asset base units, never a
+ * number and never a decimal string.
+ */
+import { isAddress, isBytes32, ok } from "../_shared/index.js";
+import { validationError } from "../errors.js";
+/** The registry key for an Asset: `<chainId>:<address>`, lower-cased. */
+export const assetKey = (asset) => `${asset.chainId.toString(10)}:${asset.address.toLowerCase()}`;
+export const sameAsset = (a, b) => assetKey(a) === assetKey(b);
+/** A 20-byte address as a 32-byte topic. */
+export const addressTopic = (address) => `0x${address.slice(2).toLowerCase().padStart(64, "0")}`;
+export function supportsAsset(strategy, asset, onThrow) {
+    try {
+        return strategy.supports(asset) === true;
+    }
+    catch (error) {
+        onThrow?.(error);
+        return false;
+    }
+}
+export function validateAssetRef(value, label) {
+    if (typeof value !== "object" || value === null) {
+        return validationError("ASSET_REF_INVALID", `${label} must be an object describing one Asset`);
+    }
+    const candidate = value;
+    if (typeof candidate.chainId !== "bigint" || candidate.chainId <= 0n) {
+        return validationError("ASSET_REF_INVALID", `${label}.chainId must be a positive bigint EVM chain id`);
+    }
+    if (!isAddress(candidate.address)) {
+        return validationError("ASSET_REF_INVALID", `${label}.address must be a 20-byte 0x address`);
+    }
+    if (typeof candidate.decimals !== "number" ||
+        !Number.isInteger(candidate.decimals) ||
+        candidate.decimals < 0) {
+        return validationError("ASSET_REF_INVALID", `${label}.decimals must be a non-negative integer`);
+    }
+    if (typeof candidate.symbol !== "string" || candidate.symbol.length === 0) {
+        return validationError("ASSET_REF_INVALID", `${label}.symbol must be a non-empty string`);
+    }
+    return ok(candidate);
+}
+export function validatePaymentStrategy(value, label = "strategy") {
+    if (typeof value !== "object" || value === null) {
+        return validationError("STRATEGY_INVALID", `${label} must be an object implementing PaymentStrategy`);
+    }
+    const candidate = value;
+    if (typeof candidate.id !== "string" || candidate.id.trim().length === 0) {
+        return validationError("STRATEGY_INVALID", `${label}.id must be a non-empty string`);
+    }
+    const id = candidate.id;
+    if (!Array.isArray(candidate.chainIds) || candidate.chainIds.length === 0) {
+        return validationError("STRATEGY_INVALID", `${label} \`${id}\` must declare at least one chain id in chainIds`);
+    }
+    for (const chainId of candidate.chainIds) {
+        if (typeof chainId !== "bigint") {
+            return validationError("STRATEGY_INVALID", `${label} \`${id}\` must declare every chain id as a bigint, received ${typeof chainId}`);
+        }
+    }
+    for (const method of ["supports", "quote", "settle"]) {
+        if (typeof candidate[method] !== "function") {
+            return validationError("STRATEGY_INVALID", `${label} \`${id}\` must implement ${method}()`);
+        }
+    }
+    if (candidate.settleBatch !== undefined && typeof candidate.settleBatch !== "function") {
+        return validationError("STRATEGY_INVALID", `${label} \`${id}\` declares settleBatch but it is not a function; leave it undefined when there is no batch form`);
+    }
+    return ok(candidate);
+}
+export function validateChargeRequest(request) {
+    if (!isAddress(request.agent)) {
+        return validationError("CHARGE_INVALID", "request.agent must be a 20-byte 0x address");
+    }
+    if (!isBytes32(request.serviceId)) {
+        return validationError("CHARGE_INVALID", "request.serviceId must be a 32-byte 0x word");
+    }
+    const asset = validateAssetRef(request.asset, "request.asset");
+    if (!asset.ok)
+        return asset;
+    if (typeof request.amount !== "bigint") {
+        return validationError("CHARGE_INVALID", "request.amount must be a bigint count of Asset base units, never a number");
+    }
+    if (request.amount <= 0n) {
+        return validationError("AMOUNT_NOT_POSITIVE", "request.amount must be greater than zero base units");
+    }
+    if (request.amount > (1n << 128n) - 1n) {
+        return validationError("AMOUNT_OUT_OF_RANGE", "request.amount must fit a uint128");
+    }
+    return ok(request);
+}
+export const validateSettleRequest = validateChargeRequest;
+//# sourceMappingURL=strategy.js.map

package/dist/payments/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/payments/strategy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The payment-strategy seam.\n *\n * A strategy is how an Agent pays down an Open Tab. On Monad there is exactly one\n * way: approve the Asset and call `TabSettlement.settle`, which moves the Asset to\n * the Service and applies the Settlement in the same transaction. The seam still\n * exists so that a different signer, a smart account, a session key, or a test\n * double can stand behind the same call without the SDK caring which.\n *\n * ## What a strategy does not do\n *\n * It does not meter, it does not read tabs, and it does not decide amounts. It is\n * handed a fully specified charge and returns either a receipt or a typed error.\n * Every figure crossing this seam is a `bigint` count of Asset base units, never a\n * number and never a decimal string.\n */\nimport { isAddress, isBytes32, ok, type Address, type Bytes32, type Hex, type Result } from \"../_shared/index.js\";\nimport { validationError } from \"../errors.js\";\n\n/** One Asset a tab can be denominated in. `chainId` is the EVM chain id. */\nexport interface AssetRef {\n  readonly chainId: bigint;\n  readonly address: Address;\n  readonly decimals: number;\n  readonly symbol: string;\n}\n\n/** What a Service is asking to be paid, before any strategy is chosen. */\nexport interface ChargeRequest {\n  readonly agent: Address;\n  readonly serviceId: Bytes32;\n  readonly asset: AssetRef;\n  readonly amount: bigint;\n}\n\n/** A charge the strategy has been asked to pay. The surface resolves where the money goes. */\nexport type SettleRequest = ChargeRequest;\n\nexport interface ChargeQuote {\n  readonly amount: bigint;\n  readonly asset: AssetRef;\n  readonly feeNote: string;\n}\n\n/**\n * What came back from a Settlement.\n *\n * `settlementId`, `applied` and `toPrepaid` are read from the `Settled` event in the\n * transaction receipt. They are `null` only when the signer could not wait for the\n * receipt, in which case the transaction hash still names the payment and the registry\n * will carry the figures once it indexes the block.\n */\nexport interface SettlementReceipt {\n  readonly strategyId: string;\n  readonly chainId: bigint;\n  readonly txHash: Hex;\n  readonly asset: AssetRef;\n  readonly amount: bigint;\n  readonly payer: Address;\n  readonly serviceId: Bytes32;\n  readonly settlementId: Bytes32 | null;\n  readonly applied: bigint | null;\n  readonly toPrepaid: bigint | null;\n  readonly submittedAt: number;\n  readonly batchIndex?: number;\n}\n\nexport interface PaymentStrategy {\n  readonly id: string;\n  /** The chain ids this strategy can settle on. */\n  readonly chainIds: readonly bigint[];\n  supports(asset: AssetRef): boolean;\n  quote(request: ChargeRequest): Promise<Result<ChargeQuote>>;\n  settle(request: SettleRequest): Promise<Result<SettlementReceipt>>;\n  settleBatch?(requests: readonly SettleRequest[]): Promise<Result<readonly SettlementReceipt[]>>;\n}\n\n/** The registry key for an Asset: `<chainId>:<address>`, lower-cased. */\nexport const assetKey = (asset: AssetRef): string =>\n  `${asset.chainId.toString(10)}:${asset.address.toLowerCase()}`;\n\nexport const sameAsset = (a: AssetRef, b: AssetRef): boolean => assetKey(a) === assetKey(b);\n\n/** A 20-byte address as a 32-byte topic. */\nexport const addressTopic = (address: Address): Bytes32 =>\n  `0x${address.slice(2).toLowerCase().padStart(64, \"0\")}`;\n\nexport function supportsAsset(\n  strategy: PaymentStrategy,\n  asset: AssetRef,\n  onThrow?: (error: unknown) => void,\n): boolean {\n  try {\n    return strategy.supports(asset) === true;\n  } catch (error) {\n    onThrow?.(error);\n    return false;\n  }\n}\n\nexport function validateAssetRef(value: unknown, label: string): Result<AssetRef> {\n  if (typeof value !== \"object\" || value === null) {\n    return validationError(\"ASSET_REF_INVALID\", `${label} must be an object describing one Asset`);\n  }\n  const candidate = value as Partial<AssetRef>;\n  if (typeof candidate.chainId !== \"bigint\" || candidate.chainId <= 0n) {\n    return validationError(\"ASSET_REF_INVALID\", `${label}.chainId must be a positive bigint EVM chain id`);\n  }\n  if (!isAddress(candidate.address)) {\n    return validationError(\"ASSET_REF_INVALID\", `${label}.address must be a 20-byte 0x address`);\n  }\n  if (\n    typeof candidate.decimals !== \"number\" ||\n    !Number.isInteger(candidate.decimals) ||\n    candidate.decimals < 0\n  ) {\n    return validationError(\"ASSET_REF_INVALID\", `${label}.decimals must be a non-negative integer`);\n  }\n  if (typeof candidate.symbol !== \"string\" || candidate.symbol.length === 0) {\n    return validationError(\"ASSET_REF_INVALID\", `${label}.symbol must be a non-empty string`);\n  }\n  return ok(candidate as AssetRef);\n}\n\nexport function validatePaymentStrategy(value: unknown, label = \"strategy\"): Result<PaymentStrategy> {\n  if (typeof value !== \"object\" || value === null) {\n    return validationError(\"STRATEGY_INVALID\", `${label} must be an object implementing PaymentStrategy`);\n  }\n  const candidate = value as Partial<PaymentStrategy>;\n  if (typeof candidate.id !== \"string\" || candidate.id.trim().length === 0) {\n    return validationError(\"STRATEGY_INVALID\", `${label}.id must be a non-empty string`);\n  }\n  const id = candidate.id;\n  if (!Array.isArray(candidate.chainIds) || candidate.chainIds.length === 0) {\n    return validationError(\"STRATEGY_INVALID\", `${label} \\`${id}\\` must declare at least one chain id in chainIds`);\n  }\n  for (const chainId of candidate.chainIds) {\n    if (typeof chainId !== \"bigint\") {\n      return validationError(\n        \"STRATEGY_INVALID\",\n        `${label} \\`${id}\\` must declare every chain id as a bigint, received ${typeof chainId}`,\n      );\n    }\n  }\n  for (const method of [\"supports\", \"quote\", \"settle\"] as const) {\n    if (typeof candidate[method] !== \"function\") {\n      return validationError(\"STRATEGY_INVALID\", `${label} \\`${id}\\` must implement ${method}()`);\n    }\n  }\n  if (candidate.settleBatch !== undefined && typeof candidate.settleBatch !== \"function\") {\n    return validationError(\n      \"STRATEGY_INVALID\",\n      `${label} \\`${id}\\` declares settleBatch but it is not a function; leave it undefined when there is no batch form`,\n    );\n  }\n  return ok(candidate as PaymentStrategy);\n}\n\nexport function validateChargeRequest(request: ChargeRequest): Result<ChargeRequest> {\n  if (!isAddress(request.agent)) {\n    return validationError(\"CHARGE_INVALID\", \"request.agent must be a 20-byte 0x address\");\n  }\n  if (!isBytes32(request.serviceId)) {\n    return validationError(\"CHARGE_INVALID\", \"request.serviceId must be a 32-byte 0x word\");\n  }\n  const asset = validateAssetRef(request.asset, \"request.asset\");\n  if (!asset.ok) return asset;\n  if (typeof request.amount !== \"bigint\") {\n    return validationError(\n      \"CHARGE_INVALID\",\n      \"request.amount must be a bigint count of Asset base units, never a number\",\n    );\n  }\n  if (request.amount <= 0n) {\n    return validationError(\"AMOUNT_NOT_POSITIVE\", \"request.amount must be greater than zero base units\");\n  }\n  if (request.amount > (1n << 128n) - 1n) {\n    return validationError(\"AMOUNT_OUT_OF_RANGE\", \"request.amount must fit a uint128\");\n  }\n  return ok(request);\n}\n\nexport const validateSettleRequest = validateChargeRequest;\n"]}

package/dist/proxy/hooks.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The hook seam of the proxy layer (R23.4).
+ *
+ * A hook is a named pair of optional phases. `before` runs ahead of the proxied
+ * request, in registration order; `after` runs once the response exists, in
+ * reverse order, so the hook registered first is the last to see the response
+ * on the way out. That is the same nesting a middleware stack has, expressed as
+ * two lists rather than as recursion, because two lists are what a Service
+ * reads back when it asks "which hooks ran, and in what order".
+ *
+ * ## A hook cannot fail a request unless it says so
+ *
+ * Every phase returns a `Result`. An `err` is logged with the hook's name and
+ * the phase, and the request carries on. That is the default because a hook is
+ * observation: it logs, it annotates, it looks something up. A Service whose
+ * log shipper is down should still deliver work. The one exception is a hook
+ * that declares `critical: true`, whose `err` replaces the response with the
+ * error it returned, at the HTTP status its category maps to. A hook that
+ * *throws* is treated exactly as one that returned an `INTERNAL` error, so the
+ * distinction between "misbehaved" and "reported a problem" is the `critical`
+ * flag and never the control flow.
+ *
+ * ## What a hook can see and what it can change
+ *
+ * The context is one object per request, shared by both phases and every hook,
+ * with two writable parts. `settlement` is where a hook that looked a Settlement
+ * up on Monad attaches what it found (R23.5), and `state` is scratch a hook uses
+ * to hand something from its `before` to its `after` phase. A hook
+ * cannot replace the request or the response through the context; only a
+ * critical failure changes what goes out.
+ *
+ * Requirements: 23.4, 23.5
+ */
+import type { Result } from "../_shared/index.js";
+import type { Logger } from "../logger.js";
+import type { MeteredCharge, MeteringOutcome } from "../server/post-paid.js";
+import type { Address, Bytes32, Hex } from "../_shared/index.js";
+/**
+ * A Settlement as a hook may attach it to a request: the figures `TabBook`
+ * recorded and the Monad transaction that carried them.
+ */
+export interface SettlementView {
+    readonly settlementId: Bytes32;
+    readonly txHash: Hex;
+    readonly agent: Address;
+    readonly serviceId: Bytes32;
+    readonly asset: Address;
+    readonly amount: bigint;
+    readonly applied: bigint;
+    readonly toPrepaid: bigint;
+    readonly blockNumber?: number;
+}
+export type ProxyPhase = "before" | "after";
+export interface ProxyHookContext {
+    readonly phase: ProxyPhase;
+    /** The request as it reached the proxy, before any header was dropped for forwarding. */
+    readonly request: Request;
+    /** The response about to be returned. Present in the `after` phase only. */
+    readonly response?: Response;
+    /**
+     * The delivery the metering plugin recorded for this request, when it recorded
+     * one. Absent when the request was not metered, when metering refused it, and
+     * under `release: "before-metering"`, where the recording is still pending
+     * while the hooks run.
+     */
+    readonly charge?: MeteredCharge;
+    /** The metering outcome in full, present whenever the plugin reached one before the hooks ran. */
+    readonly metering?: MeteringOutcome;
+    /**
+     * The Settlement attached to this request, if a hook found one.
+     * Writable: attaching it is a lookup hook's job (R23.5).
+     */
+    settlement?: SettlementView;
+    /** Scratch for the life of one request. Convention: keyed by hook name. */
+    readonly state: Map<string, unknown>;
+    readonly logger: Logger;
+}
+export interface ProxyHook {
+    /** Names the hook in logs and in `state`. Unique within one proxy. */
+    readonly name: string;
+    /**
+     * When true, an `err` from either phase fails the request with that error.
+     * Defaults to false: a hook observes, and observation failing is not a reason
+     * to withhold delivered work.
+     */
+    readonly critical?: boolean;
+    before?(context: ProxyHookContext): Promise<Result<void>>;
+    after?(context: ProxyHookContext): Promise<Result<void>>;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/proxy/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/proxy/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,KAAK,CAAC,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;CAC1D"}

package/dist/proxy/hooks.js

@@ -0,0 +1,35 @@
+/**
+ * The hook seam of the proxy layer (R23.4).
+ *
+ * A hook is a named pair of optional phases. `before` runs ahead of the proxied
+ * request, in registration order; `after` runs once the response exists, in
+ * reverse order, so the hook registered first is the last to see the response
+ * on the way out. That is the same nesting a middleware stack has, expressed as
+ * two lists rather than as recursion, because two lists are what a Service
+ * reads back when it asks "which hooks ran, and in what order".
+ *
+ * ## A hook cannot fail a request unless it says so
+ *
+ * Every phase returns a `Result`. An `err` is logged with the hook's name and
+ * the phase, and the request carries on. That is the default because a hook is
+ * observation: it logs, it annotates, it looks something up. A Service whose
+ * log shipper is down should still deliver work. The one exception is a hook
+ * that declares `critical: true`, whose `err` replaces the response with the
+ * error it returned, at the HTTP status its category maps to. A hook that
+ * *throws* is treated exactly as one that returned an `INTERNAL` error, so the
+ * distinction between "misbehaved" and "reported a problem" is the `critical`
+ * flag and never the control flow.
+ *
+ * ## What a hook can see and what it can change
+ *
+ * The context is one object per request, shared by both phases and every hook,
+ * with two writable parts. `settlement` is where a hook that looked a Settlement
+ * up on Monad attaches what it found (R23.5), and `state` is scratch a hook uses
+ * to hand something from its `before` to its `after` phase. A hook
+ * cannot replace the request or the response through the context; only a
+ * critical failure changes what goes out.
+ *
+ * Requirements: 23.4, 23.5
+ */
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/proxy/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/proxy/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG","sourcesContent":["/**\n * The hook seam of the proxy layer (R23.4).\n *\n * A hook is a named pair of optional phases. `before` runs ahead of the proxied\n * request, in registration order; `after` runs once the response exists, in\n * reverse order, so the hook registered first is the last to see the response\n * on the way out. That is the same nesting a middleware stack has, expressed as\n * two lists rather than as recursion, because two lists are what a Service\n * reads back when it asks \"which hooks ran, and in what order\".\n *\n * ## A hook cannot fail a request unless it says so\n *\n * Every phase returns a `Result`. An `err` is logged with the hook's name and\n * the phase, and the request carries on. That is the default because a hook is\n * observation: it logs, it annotates, it looks something up. A Service whose\n * log shipper is down should still deliver work. The one exception is a hook\n * that declares `critical: true`, whose `err` replaces the response with the\n * error it returned, at the HTTP status its category maps to. A hook that\n * *throws* is treated exactly as one that returned an `INTERNAL` error, so the\n * distinction between \"misbehaved\" and \"reported a problem\" is the `critical`\n * flag and never the control flow.\n *\n * ## What a hook can see and what it can change\n *\n * The context is one object per request, shared by both phases and every hook,\n * with two writable parts. `settlement` is where a hook that looked a Settlement\n * up on Monad attaches what it found (R23.5), and `state` is scratch a hook uses\n * to hand something from its `before` to its `after` phase. A hook\n * cannot replace the request or the response through the context; only a\n * critical failure changes what goes out.\n *\n * Requirements: 23.4, 23.5\n */\n\nimport type { Result } from \"../_shared/index.js\";\nimport type { Logger } from \"../logger.js\";\nimport type { MeteredCharge, MeteringOutcome } from \"../server/post-paid.js\";\nimport type { Address, Bytes32, Hex } from \"../_shared/index.js\";\n\n/**\n * A Settlement as a hook may attach it to a request: the figures `TabBook`\n * recorded and the Monad transaction that carried them.\n */\nexport interface SettlementView {\n  readonly settlementId: Bytes32;\n  readonly txHash: Hex;\n  readonly agent: Address;\n  readonly serviceId: Bytes32;\n  readonly asset: Address;\n  readonly amount: bigint;\n  readonly applied: bigint;\n  readonly toPrepaid: bigint;\n  readonly blockNumber?: number;\n}\n\nexport type ProxyPhase = \"before\" | \"after\";\n\nexport interface ProxyHookContext {\n  readonly phase: ProxyPhase;\n  /** The request as it reached the proxy, before any header was dropped for forwarding. */\n  readonly request: Request;\n  /** The response about to be returned. Present in the `after` phase only. */\n  readonly response?: Response;\n  /**\n   * The delivery the metering plugin recorded for this request, when it recorded\n   * one. Absent when the request was not metered, when metering refused it, and\n   * under `release: \"before-metering\"`, where the recording is still pending\n   * while the hooks run.\n   */\n  readonly charge?: MeteredCharge;\n  /** The metering outcome in full, present whenever the plugin reached one before the hooks ran. */\n  readonly metering?: MeteringOutcome;\n  /**\n   * The Settlement attached to this request, if a hook found one.\n   * Writable: attaching it is a lookup hook's job (R23.5).\n   */\n  settlement?: SettlementView;\n  /** Scratch for the life of one request. Convention: keyed by hook name. */\n  readonly state: Map<string, unknown>;\n  readonly logger: Logger;\n}\n\nexport interface ProxyHook {\n  /** Names the hook in logs and in `state`. Unique within one proxy. */\n  readonly name: string;\n  /**\n   * When true, an `err` from either phase fails the request with that error.\n   * Defaults to false: a hook observes, and observation failing is not a reason\n   * to withhold delivered work.\n   */\n  readonly critical?: boolean;\n  before?(context: ProxyHookContext): Promise<Result<void>>;\n  after?(context: ProxyHookContext): Promise<Result<void>>;\n}\n"]}

package/dist/proxy/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The proxy layer: hooks around a forwarded, metered request (R23.4), with a
+ * seam for attaching the Settlement that covers it (R23.5).
+ *
+ * `hooks.ts` is the seam and `proxy.ts` the handler.
+ */
+export * from "./hooks.js";
+export * from "./proxy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/proxy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/proxy/index.js

@@ -0,0 +1,9 @@
+/**
+ * The proxy layer: hooks around a forwarded, metered request (R23.4), with a
+ * seam for attaching the Settlement that covers it (R23.5).
+ *
+ * `hooks.ts` is the seam and `proxy.ts` the handler.
+ */
+export * from "./hooks.js";
+export * from "./proxy.js";
+//# sourceMappingURL=index.js.map

package/dist/proxy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC","sourcesContent":["/**\n * The proxy layer: hooks around a forwarded, metered request (R23.4), with a\n * seam for attaching the Settlement that covers it (R23.5).\n *\n * `hooks.ts` is the seam and `proxy.ts` the handler.\n */\n\nexport * from \"./hooks.js\";\nexport * from \"./proxy.js\";\n"]}