@absolutejs/mcp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.16.0 — 2026-09-11
+
+### Added
+
+- **Add account-bound billing status, paginated receipts, bounded usage and reviewed billing-management links**
+
+## 0.15.1 — 2026-09-11
+
+### Fixed
+
+- **Build and test before publishing so checkout exports are present in the distributed artifact**
+
 ## 0.15.0 — 2026-09-11
 
 ### Added

package/README.md

@@ -431,3 +431,5 @@ on the Change Date.
 ## Secure credit checkout
 
 `createCheckoutHandoffTool` and `createPurchaseStatusTool` provide account-bound credit checkout and recovery contracts. The issuer must bind server pricing and identity; route these tools through the commerce guard. Checkout is classified as `external_checkout`, so restricted and unverified channels cannot discover or execute it. Status works at zero credits. Never pass card data in tool input. See [host rules](docs/commerce-host-rules.md).
+
+`createBillingReportTools` binds billing status, paginated receipts, and bounded UTC usage reports to authenticated reader callbacks. These non-transactional tools remain available at zero balance. The shared billing projections discard payment/provider secrets and enforce reconciled usage breakdowns. `createBillingManagementTool` returns a fixed HTTPS browser page requiring normal browser authentication; because that page can initiate purchases, it retains `external_checkout` commerce classification. Never label a purchase-capable page informational to bypass host restrictions.

package/changelog.json

@@ -2,6 +2,26 @@
   "contract": 1,
   "name": "@absolutejs/mcp",
   "releases": [
+    {
+      "version": "0.16.0",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Add account-bound billing status, paginated receipts, bounded usage and reviewed billing-management links"
+        }
+      ]
+    },
+    {
+      "version": "0.15.1",
+      "date": "2026-09-11",
+      "changes": [
+        {
+          "kind": "fixed",
+          "summary": "Build and test before publishing so checkout exports are present in the distributed artifact"
+        }
+      ]
+    },
     {
       "version": "0.15.0",
       "date": "2026-09-11",

package/dist/commerce.js

@@ -59,6 +59,313 @@ var createCreditBalanceTool = (options) => ({
     };
   }
 });
+// src/checkoutTools.ts
+var record = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+var createCheckoutHandoffTool = (options) => ({
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+    title: "Open credit checkout"
+  },
+  commerce: { action: "external_checkout", categories: ["usage_credits"] },
+  description: "Prepare a short-lived credit-purchase link on the service website. The user reviews and explicitly pays there. Never send card data in chat. Does not charge a card or create a subscription.",
+  inputSchema: {
+    type: "object",
+    properties: { productId: { type: "string", minLength: 1, maxLength: 128 } },
+    required: ["productId"],
+    additionalProperties: false
+  },
+  handler: async (input) => {
+    if (!record(input) || Object.keys(input).length !== 1 || typeof input.productId !== "string" || !input.productId || input.productId.length > 128)
+      throw new Error("A productId is required");
+    const result = await options.issue(input.productId);
+    const url = new URL(result.url);
+    if (url.protocol !== "https:" || url.origin !== new URL(options.origin).origin || url.username || url.password || !Number.isFinite(Date.parse(result.expiresAt)))
+      throw new Error("Invalid checkout handoff");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Review and pay on ${url.hostname}: ${url.href}. Expires ${result.expiresAt}. No payment has been made.`
+        }
+      ],
+      structuredContent: {
+        purchaseId: result.purchaseId,
+        url: url.href,
+        expiresAt: result.expiresAt
+      }
+    };
+  }
+});
+var createPurchaseStatusTool = (options) => ({
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false
+  },
+  commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+  description: "Read this account's credit-purchase status. Available at zero balance. Does not initiate or retry payment.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      purchaseId: { type: "string", minLength: 1, maxLength: 128 }
+    },
+    required: ["purchaseId"],
+    additionalProperties: false
+  },
+  handler: async (input) => {
+    if (!record(input) || Object.keys(input).length !== 1 || typeof input.purchaseId !== "string" || !input.purchaseId || input.purchaseId.length > 128)
+      throw new Error("A purchaseId is required");
+    const value = await options.read(input.purchaseId);
+    if (!value)
+      return "No purchase with that ID exists for this account.";
+    if (value.purchaseId !== input.purchaseId || ![
+      "not_started",
+      "pending",
+      "approved",
+      "declined",
+      "refunded",
+      "reconciliation"
+    ].includes(value.status) || !Number.isSafeInteger(value.creditsGranted) || value.creditsGranted < 0)
+      throw new Error("Purchase status is unavailable");
+    const summary = {
+      purchaseId: value.purchaseId,
+      status: value.status,
+      creditsGranted: value.creditsGranted
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Purchase ${summary.status}; ${summary.creditsGranted} credits granted.`
+        }
+      ],
+      structuredContent: summary
+    };
+  }
+});
+// node_modules/@absolutejs/billing/dist/reports.js
+var DAY_MS = 86400000;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var record2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var only = (input, keys) => {
+  if (!record2(input) || Object.keys(input).some((key) => !keys.includes(key)))
+    throw new Error("Invalid report input");
+  return input;
+};
+var integer = (value) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error("Invalid report amount");
+  return value;
+};
+var iso = (value) => {
+  if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value)
+    throw new Error("Invalid report timestamp");
+  return value;
+};
+var day = (value) => {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value) || new Date(value + "T00:00:00.000Z").toISOString().slice(0, 10) !== value)
+    throw new Error("Expected a UTC calendar date");
+  return value;
+};
+var parseUsageRange = (input, now = new Date) => {
+  const args = only(input, ["from", "to"]);
+  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()) + DAY_MS);
+  const to = day(args.to ?? tomorrow.toISOString().slice(0, 10));
+  const from = day(args.from ?? new Date(Date.parse(to) - 30 * DAY_MS).toISOString().slice(0, 10));
+  const duration = Date.parse(to) - Date.parse(from);
+  if (duration <= 0 || duration > 90 * DAY_MS || Date.parse(to) > tomorrow.getTime())
+    throw new Error("Choose a range of 1\u201390 UTC days, ending no later than tomorrow");
+  return { from, to };
+};
+var parseReceiptPage = (input) => {
+  const args = only(input, ["limit", "cursor"]);
+  const limit = args.limit ?? 20;
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
+    throw new Error("Receipt limit must be 1\u201350");
+  if (args.cursor === undefined || args.cursor === null)
+    return { limit, cursor: null };
+  if (typeof args.cursor !== "string" || args.cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(args.cursor))
+    throw new Error("Invalid receipt cursor");
+  const decoded = JSON.parse(Buffer.from(args.cursor, "base64url").toString("utf8"));
+  if (!record2(decoded) || typeof decoded.at !== "string" || typeof decoded.id !== "string" || !UUID.test(decoded.id))
+    throw new Error("Invalid receipt cursor");
+  return { limit, cursor: { at: iso(decoded.at), id: decoded.id } };
+};
+var projectBillingStatus = (value) => ({
+  portalAccess: value.portalAccess === true,
+  subscription: value.subscription ? {
+    status: String(value.subscription.status).slice(0, 64),
+    renewsAt: value.subscription.renewsAt === null ? null : iso(value.subscription.renewsAt),
+    cancelAtPeriodEnd: value.subscription.cancelAtPeriodEnd === true
+  } : null,
+  credits: {
+    remaining: integer(value.credits.remaining),
+    reserved: integer(value.credits.reserved),
+    purchased: integer(value.credits.purchased),
+    promotional: integer(value.credits.promotional),
+    debt: integer(value.credits.debt)
+  },
+  automaticRefill: false
+});
+var projectReceiptPage = (value, limit) => {
+  if (value.receipts.length > limit)
+    throw new Error("Receipt page exceeds its limit");
+  if (value.nextCursor !== null)
+    parseReceiptPage({ cursor: value.nextCursor });
+  return {
+    receipts: value.receipts.map((row) => {
+      if (!UUID.test(row.id) || !/^[A-Z]{3}$/.test(row.currency) || !["credit_purchase", "initial", "plan_change", "renewal"].includes(row.source) || !["paid", "partially_refunded", "refunded"].includes(row.status) || row.refundedAmountCents > row.amountCents)
+        throw new Error("Invalid receipt");
+      return {
+        id: row.id,
+        issuedAt: iso(row.issuedAt),
+        currency: row.currency,
+        amountCents: integer(row.amountCents),
+        refundedAmountCents: integer(row.refundedAmountCents),
+        source: row.source,
+        status: row.status
+      };
+    }),
+    nextCursor: value.nextCursor
+  };
+};
+var projectUsageReport = (value, range) => {
+  if (value.from !== range.from || value.to !== range.to || value.byDay.length > 90 || value.byFeature.length > 21)
+    throw new Error("Invalid usage report bounds");
+  const byDay = value.byDay.map((row) => ({
+    day: day(row.day),
+    credits: integer(row.credits),
+    events: integer(row.events)
+  }));
+  const byFeature = value.byFeature.map((row) => ({
+    feature: row.feature.slice(0, 128),
+    credits: integer(row.credits),
+    events: integer(row.events)
+  }));
+  const credits = integer(value.creditsConsumed), events = integer(value.events);
+  for (const rows of [byDay, byFeature])
+    if (rows.reduce((sum, row) => sum + row.credits, 0) !== credits || rows.reduce((sum, row) => sum + row.events, 0) !== events)
+      throw new Error("Usage breakdown does not reconcile");
+  if (new Set(byDay.map((row) => row.day)).size !== byDay.length || byDay.some((row) => row.day < range.from || row.day >= range.to))
+    throw new Error("Invalid usage days");
+  return {
+    from: range.from,
+    to: range.to,
+    creditsConsumed: credits,
+    events,
+    byDay,
+    byFeature
+  };
+};
+
+// src/billingTools.ts
+var result = (text, data) => ({
+  content: [{ type: "text", text }],
+  structuredContent: { ...data }
+});
+var empty = (input) => {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length)
+    throw new Error("This tool takes no arguments");
+};
+var createBillingReportTools = (readers) => ({
+  get_billing_status: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: {
+      action: "entitlement_status",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "Read subscription and service-credit status for this account, including reserved credits and debt. Does not charge, renew or cancel anything. Available at zero balance.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      empty(input);
+      const status = projectBillingStatus(await readers.status());
+      return result(`${status.credits.remaining} service credits available, ${status.credits.reserved} reserved. Portal access: ${status.portalAccess ? "enabled" : "not enabled"}. Automatic refill is off.`, status);
+    }
+  },
+  list_receipts: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: {
+      action: "entitlement_status",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "List this account's payment receipts, newest first, with original amounts and refunds recorded to date. Amounts are currency minor units, not consumed credits. Follow nextCursor for more. No payment credentials or provider references are exposed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 50, default: 20 },
+        cursor: { type: ["string", "null"], maxLength: 256 }
+      },
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const request = parseReceiptPage(input);
+      const page = projectReceiptPage(await readers.receipts(request), request.limit);
+      return result(`${page.receipts.length} receipts.${page.nextCursor ? " More receipts are available using nextCursor." : ""}`, page);
+    }
+  },
+  get_usage_report: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+    description: "Read recorded service-credit consumption by UTC day and feature. from is inclusive and to is exclusive; at most 90 days, default last 30 days including today. Credits consumed are not dollars paid or the assistant's own tokens. Does not estimate ROI or expose internal provider costs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", format: "date" },
+        to: { type: "string", format: "date" }
+      },
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const range = parseUsageRange(input, readers.now?.());
+      const usage = projectUsageReport(await readers.usage(range), range);
+      return result(`${usage.creditsConsumed} service credits across ${usage.events} recorded events, ${range.from} inclusive to ${range.to} exclusive (UTC).`, usage);
+    }
+  }
+});
+var createBillingManagementTool = (destination) => {
+  const url = new URL(destination);
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
+    throw new Error("Billing management requires a fixed HTTPS page URL");
+  return {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true
+    },
+    commerce: {
+      action: "external_checkout",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "Open the service's authenticated billing page to buy credits, review receipts, or manage an existing subscription. Uses a matching browser login; may require sign-in. This link does not grant a login session or authorize any payment.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      empty(input);
+      return result(`Manage billing on ${url.hostname}: ${url.href}. Sign in if needed; changes require your confirmation.`, { url: url.href, requiresBrowserAuthentication: true });
+    }
+  };
+};
 
 // src/commerce.ts
 var COMMERCE_POLICY_VERSION = "2026-09-10.1";
@@ -168,6 +475,10 @@ var evaluateCommerce = (req, context, now = new Date) => {
 export {
   COMMERCE_POLICY_SOURCES,
   COMMERCE_POLICY_VERSION,
+  createBillingManagementTool,
+  createBillingReportTools,
+  createCheckoutHandoffTool,
   createCreditBalanceTool,
+  createPurchaseStatusTool,
   evaluateCommerce
 };

package/dist/index.js

@@ -59,6 +59,313 @@ var createCreditBalanceTool = (options) => ({
     };
   }
 });
+// src/checkoutTools.ts
+var record = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+var createCheckoutHandoffTool = (options) => ({
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+    title: "Open credit checkout"
+  },
+  commerce: { action: "external_checkout", categories: ["usage_credits"] },
+  description: "Prepare a short-lived credit-purchase link on the service website. The user reviews and explicitly pays there. Never send card data in chat. Does not charge a card or create a subscription.",
+  inputSchema: {
+    type: "object",
+    properties: { productId: { type: "string", minLength: 1, maxLength: 128 } },
+    required: ["productId"],
+    additionalProperties: false
+  },
+  handler: async (input) => {
+    if (!record(input) || Object.keys(input).length !== 1 || typeof input.productId !== "string" || !input.productId || input.productId.length > 128)
+      throw new Error("A productId is required");
+    const result = await options.issue(input.productId);
+    const url = new URL(result.url);
+    if (url.protocol !== "https:" || url.origin !== new URL(options.origin).origin || url.username || url.password || !Number.isFinite(Date.parse(result.expiresAt)))
+      throw new Error("Invalid checkout handoff");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Review and pay on ${url.hostname}: ${url.href}. Expires ${result.expiresAt}. No payment has been made.`
+        }
+      ],
+      structuredContent: {
+        purchaseId: result.purchaseId,
+        url: url.href,
+        expiresAt: result.expiresAt
+      }
+    };
+  }
+});
+var createPurchaseStatusTool = (options) => ({
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false
+  },
+  commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+  description: "Read this account's credit-purchase status. Available at zero balance. Does not initiate or retry payment.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      purchaseId: { type: "string", minLength: 1, maxLength: 128 }
+    },
+    required: ["purchaseId"],
+    additionalProperties: false
+  },
+  handler: async (input) => {
+    if (!record(input) || Object.keys(input).length !== 1 || typeof input.purchaseId !== "string" || !input.purchaseId || input.purchaseId.length > 128)
+      throw new Error("A purchaseId is required");
+    const value = await options.read(input.purchaseId);
+    if (!value)
+      return "No purchase with that ID exists for this account.";
+    if (value.purchaseId !== input.purchaseId || ![
+      "not_started",
+      "pending",
+      "approved",
+      "declined",
+      "refunded",
+      "reconciliation"
+    ].includes(value.status) || !Number.isSafeInteger(value.creditsGranted) || value.creditsGranted < 0)
+      throw new Error("Purchase status is unavailable");
+    const summary = {
+      purchaseId: value.purchaseId,
+      status: value.status,
+      creditsGranted: value.creditsGranted
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Purchase ${summary.status}; ${summary.creditsGranted} credits granted.`
+        }
+      ],
+      structuredContent: summary
+    };
+  }
+});
+// node_modules/@absolutejs/billing/dist/reports.js
+var DAY_MS = 86400000;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var record2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var only = (input, keys) => {
+  if (!record2(input) || Object.keys(input).some((key) => !keys.includes(key)))
+    throw new Error("Invalid report input");
+  return input;
+};
+var integer = (value) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error("Invalid report amount");
+  return value;
+};
+var iso = (value) => {
+  if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value)
+    throw new Error("Invalid report timestamp");
+  return value;
+};
+var day = (value) => {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value) || new Date(value + "T00:00:00.000Z").toISOString().slice(0, 10) !== value)
+    throw new Error("Expected a UTC calendar date");
+  return value;
+};
+var parseUsageRange = (input, now = new Date) => {
+  const args = only(input, ["from", "to"]);
+  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()) + DAY_MS);
+  const to = day(args.to ?? tomorrow.toISOString().slice(0, 10));
+  const from = day(args.from ?? new Date(Date.parse(to) - 30 * DAY_MS).toISOString().slice(0, 10));
+  const duration = Date.parse(to) - Date.parse(from);
+  if (duration <= 0 || duration > 90 * DAY_MS || Date.parse(to) > tomorrow.getTime())
+    throw new Error("Choose a range of 1\u201390 UTC days, ending no later than tomorrow");
+  return { from, to };
+};
+var parseReceiptPage = (input) => {
+  const args = only(input, ["limit", "cursor"]);
+  const limit = args.limit ?? 20;
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
+    throw new Error("Receipt limit must be 1\u201350");
+  if (args.cursor === undefined || args.cursor === null)
+    return { limit, cursor: null };
+  if (typeof args.cursor !== "string" || args.cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(args.cursor))
+    throw new Error("Invalid receipt cursor");
+  const decoded = JSON.parse(Buffer.from(args.cursor, "base64url").toString("utf8"));
+  if (!record2(decoded) || typeof decoded.at !== "string" || typeof decoded.id !== "string" || !UUID.test(decoded.id))
+    throw new Error("Invalid receipt cursor");
+  return { limit, cursor: { at: iso(decoded.at), id: decoded.id } };
+};
+var projectBillingStatus = (value) => ({
+  portalAccess: value.portalAccess === true,
+  subscription: value.subscription ? {
+    status: String(value.subscription.status).slice(0, 64),
+    renewsAt: value.subscription.renewsAt === null ? null : iso(value.subscription.renewsAt),
+    cancelAtPeriodEnd: value.subscription.cancelAtPeriodEnd === true
+  } : null,
+  credits: {
+    remaining: integer(value.credits.remaining),
+    reserved: integer(value.credits.reserved),
+    purchased: integer(value.credits.purchased),
+    promotional: integer(value.credits.promotional),
+    debt: integer(value.credits.debt)
+  },
+  automaticRefill: false
+});
+var projectReceiptPage = (value, limit) => {
+  if (value.receipts.length > limit)
+    throw new Error("Receipt page exceeds its limit");
+  if (value.nextCursor !== null)
+    parseReceiptPage({ cursor: value.nextCursor });
+  return {
+    receipts: value.receipts.map((row) => {
+      if (!UUID.test(row.id) || !/^[A-Z]{3}$/.test(row.currency) || !["credit_purchase", "initial", "plan_change", "renewal"].includes(row.source) || !["paid", "partially_refunded", "refunded"].includes(row.status) || row.refundedAmountCents > row.amountCents)
+        throw new Error("Invalid receipt");
+      return {
+        id: row.id,
+        issuedAt: iso(row.issuedAt),
+        currency: row.currency,
+        amountCents: integer(row.amountCents),
+        refundedAmountCents: integer(row.refundedAmountCents),
+        source: row.source,
+        status: row.status
+      };
+    }),
+    nextCursor: value.nextCursor
+  };
+};
+var projectUsageReport = (value, range) => {
+  if (value.from !== range.from || value.to !== range.to || value.byDay.length > 90 || value.byFeature.length > 21)
+    throw new Error("Invalid usage report bounds");
+  const byDay = value.byDay.map((row) => ({
+    day: day(row.day),
+    credits: integer(row.credits),
+    events: integer(row.events)
+  }));
+  const byFeature = value.byFeature.map((row) => ({
+    feature: row.feature.slice(0, 128),
+    credits: integer(row.credits),
+    events: integer(row.events)
+  }));
+  const credits = integer(value.creditsConsumed), events = integer(value.events);
+  for (const rows of [byDay, byFeature])
+    if (rows.reduce((sum, row) => sum + row.credits, 0) !== credits || rows.reduce((sum, row) => sum + row.events, 0) !== events)
+      throw new Error("Usage breakdown does not reconcile");
+  if (new Set(byDay.map((row) => row.day)).size !== byDay.length || byDay.some((row) => row.day < range.from || row.day >= range.to))
+    throw new Error("Invalid usage days");
+  return {
+    from: range.from,
+    to: range.to,
+    creditsConsumed: credits,
+    events,
+    byDay,
+    byFeature
+  };
+};
+
+// src/billingTools.ts
+var result = (text, data) => ({
+  content: [{ type: "text", text }],
+  structuredContent: { ...data }
+});
+var empty = (input) => {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length)
+    throw new Error("This tool takes no arguments");
+};
+var createBillingReportTools = (readers) => ({
+  get_billing_status: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: {
+      action: "entitlement_status",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "Read subscription and service-credit status for this account, including reserved credits and debt. Does not charge, renew or cancel anything. Available at zero balance.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      empty(input);
+      const status = projectBillingStatus(await readers.status());
+      return result(`${status.credits.remaining} service credits available, ${status.credits.reserved} reserved. Portal access: ${status.portalAccess ? "enabled" : "not enabled"}. Automatic refill is off.`, status);
+    }
+  },
+  list_receipts: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: {
+      action: "entitlement_status",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "List this account's payment receipts, newest first, with original amounts and refunds recorded to date. Amounts are currency minor units, not consumed credits. Follow nextCursor for more. No payment credentials or provider references are exposed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 50, default: 20 },
+        cursor: { type: ["string", "null"], maxLength: 256 }
+      },
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const request = parseReceiptPage(input);
+      const page = projectReceiptPage(await readers.receipts(request), request.limit);
+      return result(`${page.receipts.length} receipts.${page.nextCursor ? " More receipts are available using nextCursor." : ""}`, page);
+    }
+  },
+  get_usage_report: {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+    description: "Read recorded service-credit consumption by UTC day and feature. from is inclusive and to is exclusive; at most 90 days, default last 30 days including today. Credits consumed are not dollars paid or the assistant's own tokens. Does not estimate ROI or expose internal provider costs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", format: "date" },
+        to: { type: "string", format: "date" }
+      },
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const range = parseUsageRange(input, readers.now?.());
+      const usage = projectUsageReport(await readers.usage(range), range);
+      return result(`${usage.creditsConsumed} service credits across ${usage.events} recorded events, ${range.from} inclusive to ${range.to} exclusive (UTC).`, usage);
+    }
+  }
+});
+var createBillingManagementTool = (destination) => {
+  const url = new URL(destination);
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
+    throw new Error("Billing management requires a fixed HTTPS page URL");
+  return {
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true
+    },
+    commerce: {
+      action: "external_checkout",
+      categories: ["usage_credits", "subscription"]
+    },
+    description: "Open the service's authenticated billing page to buy credits, review receipts, or manage an existing subscription. Uses a matching browser login; may require sign-in. This link does not grant a login session or authorize any payment.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      empty(input);
+      return result(`Manage billing on ${url.hostname}: ${url.href}. Sign in if needed; changes require your confirmation.`, { url: url.href, requiresBrowserAuthentication: true });
+    }
+  };
+};
 
 // src/commerce.ts
 var COMMERCE_POLICY_VERSION = "2026-09-10.1";
@@ -287,7 +594,7 @@ var createMcpClient = (options) => {
   let sessionId = null;
   let nextId = 1;
   const authorizationHeaders = (method) => options.authorization?.headers({ method, url: options.url }) ?? {};
-  const respond = async (id, result) => {
+  const respond = async (id, result2) => {
     const headers = {
       "content-type": "application/json",
       "mcp-protocol-version": protocolVersion,
@@ -297,7 +604,7 @@ var createMcpClient = (options) => {
     if (sessionId !== null)
       headers["mcp-session-id"] = sessionId;
     await doFetch(options.url, {
-      body: JSON.stringify({ id, jsonrpc: "2.0", result }),
+      body: JSON.stringify({ id, jsonrpc: "2.0", result: result2 }),
       headers,
       method: "POST"
     }).catch(() => {
@@ -318,8 +625,8 @@ var createMcpClient = (options) => {
       mode: "form",
       requestedSchema: isRecord(params.requestedSchema) ? params.requestedSchema : {}
     };
-    const result = options.onElicit ? await options.onElicit(request) : { action: "decline" };
-    await respond(message.id, request.mode === "url" && result.action === "accept" ? { action: "accept" } : result);
+    const result2 = options.onElicit ? await options.onElicit(request) : { action: "decline" };
+    await respond(message.id, request.mode === "url" && result2.action === "accept" ? { action: "accept" } : result2);
   };
   const rpc = async (method, params) => {
     const controller = new AbortController;
@@ -404,7 +711,7 @@ var createMcpClient = (options) => {
     });
   };
   const initialize = async () => {
-    const result = await rpc("initialize", {
+    const result2 = await rpc("initialize", {
       capabilities: options.onElicit ? { elicitation: { form: {}, url: {} } } : {},
       clientInfo: options.clientInfo ?? {
         name: "@absolutejs/mcp",
@@ -412,19 +719,19 @@ var createMcpClient = (options) => {
       },
       protocolVersion
     });
-    if (isRecord(result) && typeof result.protocolVersion === "string") {
-      protocolVersion = result.protocolVersion;
+    if (isRecord(result2) && typeof result2.protocolVersion === "string") {
+      protocolVersion = result2.protocolVersion;
     }
     await notify("notifications/initialized");
-    return isRecord(result) ? result : {};
+    return isRecord(result2) ? result2 : {};
   };
   const MAX_LIST_PAGES = 40;
   const listTools = async () => {
     const collected = [];
     let cursor;
     for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
-      const result = await rpc("tools/list", cursor === undefined ? undefined : { cursor });
-      const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
+      const result2 = await rpc("tools/list", cursor === undefined ? undefined : { cursor });
+      const tools = isRecord(result2) && Array.isArray(result2.tools) ? result2.tools : [];
       collected.push(...tools.filter(isRecord).map((tool) => ({
         annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
         coaz: typeof tool.coaz === "boolean" ? tool.coaz : undefined,
@@ -434,7 +741,7 @@ var createMcpClient = (options) => {
         outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined,
         taskSupport: isRecord(tool.execution) && (tool.execution.taskSupport === "forbidden" || tool.execution.taskSupport === "optional" || tool.execution.taskSupport === "required") ? tool.execution.taskSupport : undefined
       })));
-      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      const next = isRecord(result2) && typeof result2.nextCursor === "string" ? result2.nextCursor : undefined;
       if (next === undefined)
         break;
       cursor = next;
@@ -442,9 +749,9 @@ var createMcpClient = (options) => {
     return collected;
   };
   const callTool = async (name, args) => {
-    const result = await rpc("tools/call", { arguments: args ?? {}, name });
-    if (isRecord(result) && Array.isArray(result.content)) {
-      return result;
+    const result2 = await rpc("tools/call", { arguments: args ?? {}, name });
+    if (isRecord(result2) && Array.isArray(result2.content)) {
+      return result2;
     }
     return { content: [], isError: false };
   };
@@ -455,31 +762,31 @@ var createMcpClient = (options) => {
     return value;
   };
   const callToolAsTask = async (name, args, options2 = {}) => {
-    const result = await rpc("tools/call", {
+    const result2 = await rpc("tools/call", {
       arguments: args ?? {},
       name,
       task: options2.ttl === undefined ? {} : { ttl: options2.ttl }
     });
-    return taskFrom(isRecord(result) ? result.task : undefined);
+    return taskFrom(isRecord(result2) ? result2.task : undefined);
   };
   const getTask = async (taskId) => taskFrom(await rpc("tasks/get", { taskId }));
   const cancelTask = async (taskId) => taskFrom(await rpc("tasks/cancel", { taskId }));
   const getTaskResult = async (taskId) => {
-    const result = await rpc("tasks/result", { taskId });
-    if (!isRecord(result) || !Array.isArray(result.content)) {
+    const result2 = await rpc("tasks/result", { taskId });
+    if (!isRecord(result2) || !Array.isArray(result2.content)) {
       throw new McpClientError("Malformed MCP task result");
     }
-    return result;
+    return result2;
   };
   const listTasks = async () => {
     const collected = [];
     let cursor;
     for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
-      const result = await rpc("tasks/list", cursor === undefined ? undefined : { cursor });
-      if (isRecord(result) && Array.isArray(result.tasks)) {
-        collected.push(...result.tasks.map(taskFrom));
+      const result2 = await rpc("tasks/list", cursor === undefined ? undefined : { cursor });
+      if (isRecord(result2) && Array.isArray(result2.tasks)) {
+        collected.push(...result2.tasks.map(taskFrom));
       }
-      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      const next = isRecord(result2) && typeof result2.nextCursor === "string" ? result2.nextCursor : undefined;
       if (next === undefined)
         break;
       cursor = next;
@@ -490,11 +797,11 @@ var createMcpClient = (options) => {
     const collected = [];
     let cursor;
     for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
-      const result = await rpc("resources/list", cursor === undefined ? undefined : { cursor });
-      if (isRecord(result) && Array.isArray(result.resources)) {
-        collected.push(...result.resources);
+      const result2 = await rpc("resources/list", cursor === undefined ? undefined : { cursor });
+      if (isRecord(result2) && Array.isArray(result2.resources)) {
+        collected.push(...result2.resources);
       }
-      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      const next = isRecord(result2) && typeof result2.nextCursor === "string" ? result2.nextCursor : undefined;
       if (next === undefined)
         break;
       cursor = next;
@@ -763,17 +1070,17 @@ var createMcpOAuthProvider = (options) => {
         redirectUri: options.redirectUri,
         scopes
       });
-      const result = await options.onAuthorize({
+      const result2 = await options.onAuthorize({
         authorizationUrl: request.authorizationUrl,
         state: request.state,
         scopes,
         resource: found.resource.resource
       });
-      if (result.state !== request.state)
+      if (result2.state !== request.state)
         throw new Error("OAuth state mismatch");
       const params = new URLSearchParams({
         grant_type: "authorization_code",
-        code: result.code,
+        code: result2.code,
         client_id: options.clientId,
         redirect_uri: options.redirectUri,
         code_verifier: request.codeVerifier,
@@ -813,7 +1120,7 @@ var HTTP_METHOD_NOT_ALLOWED = 405;
 var jsonHeaders = {
   "content-type": "application/json"
 };
-var rpcResult = (id, result) => new Response(JSON.stringify({ id, jsonrpc: "2.0", result }), {
+var rpcResult = (id, result2) => new Response(JSON.stringify({ id, jsonrpc: "2.0", result: result2 }), {
   headers: jsonHeaders
 });
 var rpcError = (id, code, message, data) => new Response(JSON.stringify({
@@ -877,7 +1184,7 @@ var createMemoryMcpTaskStore = () => {
   };
 };
 var publicMcpTask = ({ authorizationKey, ...task }) => {
-  const { error, inputRequests, pollIntervalMs, result, ttlMs, ...rest } = task;
+  const { error, inputRequests, pollIntervalMs, result: result2, ttlMs, ...rest } = task;
   return {
     ...rest,
     ...pollIntervalMs === undefined ? {} : { pollInterval: pollIntervalMs },
@@ -1056,12 +1363,12 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
         };
       return normalizeResult(await tool.handler(args, context));
     };
-    let result;
+    let result2;
     const eligibility = await commerceDecision(config, caller, name, tool);
     if (eligibility)
       meta.commerceDecision = eligibility;
     if (eligibility?.allowed === false) {
-      result = {
+      result2 = {
         content: [
           {
             type: "text",
@@ -1075,7 +1382,7 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
         }
       };
     } else if (tool.authorization === undefined) {
-      result = await invoke();
+      result2 = await invoke();
     } else {
       const agency = config.agency;
       if (agency === undefined)
@@ -1107,7 +1414,7 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
       meta.agencyActionId = requested.action.actionId;
       meta.agencyDecisionId = requested.decision.decisionId;
       if (requested.decision.kind === "deny") {
-        result = {
+        result2 = {
           content: [
             {
               text: requested.decision.requestable ? `Action requires approval (${requested.action.actionId})` : `Action denied: ${requested.decision.reason}`,
@@ -1130,11 +1437,11 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
         });
         meta.agencyLeaseId = lease.leaseId;
         meta.agencyReceiptId = executed.receipt.receiptId;
-        result = executed.result;
+        result2 = executed.result;
       }
     }
-    ok = result.isError !== true;
-    payload = { id, jsonrpc: "2.0", result };
+    ok = result2.isError !== true;
+    payload = { id, jsonrpc: "2.0", result: result2 };
   } catch (error) {
     const detail = error instanceof Error ? error.message : "unknown error";
     payload = {
@@ -1261,10 +1568,10 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
     await tasks.store.save(task);
     setTimeout(() => {
       runTool(config, caller, scopes, id, name, args, meta, tool, noElicit).then(async (payload2) => {
-        const result = isRecord(payload2) && isRecord(payload2.result) ? payload2.result : { content: [], isError: true };
+        const result2 = isRecord(payload2) && isRecord(payload2.result) ? payload2.result : { content: [], isError: true };
         await tasks.store.update(task.taskId, {
-          result,
-          status: result.isError === true ? "failed" : "completed"
+          result: result2,
+          status: result2.isError === true ? "failed" : "completed"
         });
       }).catch(async (error) => {
         await tasks.store.update(task.taskId, {
@@ -1328,14 +1635,14 @@ var tasksResult = async (config, caller, id, params, signal) => {
   if (task.error !== undefined) {
     return rpcError(id, typeof task.error.code === "number" ? task.error.code : JSONRPC_INTERNAL_ERROR, typeof task.error.message === "string" ? task.error.message : "Task failed");
   }
-  const result = task.result ?? {
+  const result2 = task.result ?? {
     content: [],
     isError: task.status !== "completed"
   };
   return rpcResult(id, {
-    ...result,
+    ...result2,
     _meta: {
-      ...isRecord(result._meta) ? result._meta : {},
+      ...isRecord(result2._meta) ? result2._meta : {},
       "io.modelcontextprotocol/related-task": { taskId: task.taskId }
     }
   });
@@ -1461,11 +1768,11 @@ var elicitAnswer = async (message, context) => {
   const requestId = typeof message.id === "string" ? message.id : null;
   if (!requestId || !context.sessions)
     return notificationAck();
-  const result = isRecord(message.result) ? message.result : null;
-  const action = result?.action;
+  const result2 = isRecord(message.result) ? message.result : null;
+  const action = result2?.action;
   const answer = action === "accept" ? {
     action: "accept",
-    content: isRecord(result?.content) ? result.content : {}
+    content: isRecord(result2?.content) ? result2.content : {}
   } : action === "decline" ? { action: "decline" } : { action: "cancel" };
   await context.sessions.resolveElicit({
     requestId,
@@ -1917,9 +2224,9 @@ var createPostgresMcpTaskStore = ({
     update: async (taskId, update) => {
       const updatedAt = now().toISOString();
       const data = { ...update, lastUpdatedAt: updatedAt };
-      const result = await client.query(`UPDATE ${ns}.tasks SET status = COALESCE($2::text, status), updated_at = $3::timestamptz, data = data || $4::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed') RETURNING data`, [taskId, update.status ?? null, updatedAt, JSON.stringify(data)]);
-      if (result.rows[0] !== undefined)
-        return result.rows[0].data;
+      const result2 = await client.query(`UPDATE ${ns}.tasks SET status = COALESCE($2::text, status), updated_at = $3::timestamptz, data = data || $4::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed') RETURNING data`, [taskId, update.status ?? null, updatedAt, JSON.stringify(data)]);
+      if (result2.rows[0] !== undefined)
+        return result2.rows[0].data;
       return (await client.query(`SELECT data FROM ${ns}.tasks WHERE task_id = $1`, [taskId])).rows[0]?.data ?? null;
     }
   };
@@ -1951,12 +2258,12 @@ var createPostgresMcpSessionStore = ({
     },
     get: async (id) => {
       const current = now();
-      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit, can_elicit_url`, [
+      const result2 = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit, can_elicit_url`, [
         id,
         current.toISOString(),
         new Date(current.getTime() + ttlMs).toISOString()
       ]);
-      const row = result.rows[0];
+      const row = result2.rows[0];
       return row === undefined ? null : {
         canElicit: row.can_elicit,
         canElicitUrl: row.can_elicit_url
@@ -2008,6 +2315,9 @@ export {
   MCP_LATEST_PROTOCOL_VERSION,
   McpClientError,
   budgetedMcpTool,
+  createBillingManagementTool,
+  createBillingReportTools,
+  createCheckoutHandoffTool,
   createCreditBalanceTool,
   createMcpAuthorizationRequest,
   createMcpClient,
@@ -2017,6 +2327,7 @@ export {
   createMemoryMcpTaskStore,
   createPostgresMcpSessionStore,
   createPostgresMcpTaskStore,
+  createPurchaseStatusTool,
   createSessionRegistry,
   discoverMcpAuthorization,
   dispatchMcp,

package/dist/manifest.js

@@ -2861,7 +2861,9 @@ var manifest = defineManifest()({
     tagline: "Let AI assistants connect to your site and use its tools."
   },
   requires: {
-    peers: [{ name: "elysia", range: "^2.0.0-beta.6", reason: "plugin host" }]
+    peers: [
+      { name: "elysia", range: "^2.0.0-beta.6", reason: "plugin host" }
+    ]
   },
   settings: Type.Object({
     instructions: Type.Optional(Type.String({

package/dist/src/billingTools.d.ts

@@ -0,0 +1,30 @@
+import { type BillingStatus, type ReceiptPage, type ReceiptPageRequest, type UsageRange, type CustomerUsageReport } from "@absolutejs/billing/reports";
+import type { McpToolRegistry, McpToolResult } from "./types";
+/** Bind each reader to the authenticated account. Keep these reads outside
+ * paid-work gates; never include account IDs or provider credentials in input. */
+export declare const createBillingReportTools: (readers: {
+    status: () => Promise<BillingStatus>;
+    receipts: (request: ReceiptPageRequest) => Promise<ReceiptPage>;
+    usage: (range: UsageRange) => Promise<CustomerUsageReport>;
+    now?: () => Date;
+}) => McpToolRegistry;
+/** This destination can initiate purchases, so it must retain the checkout
+ * classification. A generic billing-page label cannot bypass host rules. */
+export declare const createBillingManagementTool: (destination: string) => {
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        openWorldHint: boolean;
+    };
+    commerce: {
+        action: "external_checkout";
+        categories: ("subscription" | "usage_credits")[];
+    };
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {};
+        additionalProperties: boolean;
+    };
+    handler: (input: unknown) => Promise<McpToolResult>;
+};

package/dist/src/checkoutTools.d.ts

@@ -0,0 +1,19 @@
+import type { McpTool } from "./types";
+export type McpPurchaseStatus = {
+    purchaseId: string;
+    status: "not_started" | "pending" | "approved" | "declined" | "refunded" | "reconciliation";
+    creditsGranted: number;
+};
+/** The issuer is bound to the authenticated account and canonical server pricing.
+ * Register only through the commerce guard. This tool never takes payment data. */
+export declare const createCheckoutHandoffTool: (options: {
+    origin: string;
+    issue: (productId: string) => Promise<{
+        purchaseId: string;
+        url: string;
+        expiresAt: string;
+    }>;
+}) => McpTool;
+export declare const createPurchaseStatusTool: (options: {
+    read: (purchaseId: string) => Promise<McpPurchaseStatus | null>;
+}) => McpTool;

package/dist/src/commerce.d.ts

@@ -48,3 +48,5 @@ export type CommerceDecision = {
  * Unverified paths need explicit, fresh server-side review evidence. */
 export declare const evaluateCommerce: (req: CommerceRequirement, context: CommerceContext, now?: Date) => CommerceDecision;
 export { createCreditBalanceTool, type McpCreditBalance } from "./creditStatus";
+export { createCheckoutHandoffTool, createPurchaseStatusTool, type McpPurchaseStatus, } from "./checkoutTools";
+export { createBillingReportTools, createBillingManagementTool, } from "./billingTools";

package/dist/src/index.d.ts

@@ -45,3 +45,5 @@ export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitation
 export * from "./commerce";
 export { createCreditBalanceTool, type McpCreditBalance } from "./creditStatus";
 export { budgetedMcpTool, type McpCreditWorkRequest } from "./budgetedTool";
+export { createCheckoutHandoffTool, createPurchaseStatusTool, type McpPurchaseStatus, } from "./checkoutTools";
+export { createBillingReportTools, createBillingManagementTool, } from "./billingTools";

package/package.json

@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "@absolutejs/manifest": "^0.9.0",
-    "@sinclair/typebox": "^0.34.0"
+    "@sinclair/typebox": "^0.34.0",
+    "@absolutejs/billing": "^0.9.0"
   },
   "license": "BUSL-1.1",
   "absolutejs": {
@@ -68,9 +69,9 @@
     "release": "bun run format && bun run test && bun run build && bun publish",
     "test": "bun test",
     "typecheck": "tsc --noEmit --project tsconfig.json",
-    "check:package": "absolute-changelog check",
+    "check:package": "bun run typecheck && bun run test && bun run build && absolute-changelog check",
     "prepublishOnly": "bun run check:package"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.15.0"
+  "version": "0.16.0"
 }