@develemit/billing 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @develemit/billing
+
+Typed, fetch-based client for the emit-billing API. Server-side only — the
+API key is a project-level secret, and entitlement checks must never happen
+from a browser with that key exposed.
+
+## Install
+
+```bash
+pnpm add @develemit/billing
+```
+
+## Afternoon integration
+
+```ts
+import { createClient, BillingApiError } from '@develemit/billing';
+
+const billing = createClient({
+  apiKey: process.env.BILLING_API_KEY!,
+  baseUrl: 'https://billing.example.com',
+});
+
+// Gate a route
+app.get('/reports/export', async (req, res) => {
+  const entitlements = await billing.getEntitlements(req.subjectId);
+  if (!entitlements.features.export) {
+    return res.status(403).json({ error: 'upgrade_required' });
+  }
+  // entitlements.stale === true means this came from cache after an API
+  // outage — still safe to trust for gating, just not guaranteed fresh.
+  return res.json(await buildExportReport());
+});
+
+// Start checkout
+app.post('/upgrade', async (req, res) => {
+  try {
+    const { url } = await billing.createCheckout({
+      planKey: 'pro',
+      subjectId: req.subjectId,
+      successUrl: 'https://app.example.com/billing/success',
+      cancelUrl: 'https://app.example.com/billing',
+    });
+    return res.redirect(url);
+  } catch (err) {
+    if (err instanceof BillingApiError) {
+      return res.status(502).json({ error: err.code });
+    }
+    throw err;
+  }
+});
+```
+
+## Route gating (Fastify)
+
+`billingGuardPlugin` wraps `getEntitlements` with a fail-open/fail-closed
+policy for route guards, so every gated route states — explicitly, at the
+type level — what happens when billing itself is unreachable.
+
+It lives at the `@develemit/billing/fastify` subpath rather than the
+package root, so importing the core client never pulls in Fastify's types —
+install `fastify` yourself (it's a peer dependency) only if you use this
+part of the SDK.
+
+```ts
+import { createClient } from '@develemit/billing';
+import { billingGuardPlugin } from '@develemit/billing/fastify';
+
+const billing = createClient({
+  apiKey: process.env.BILLING_API_KEY!,
+  baseUrl: 'https://billing.example.com',
+});
+
+await app.register(billingGuardPlugin, {
+  client: billing,
+  getSubjectId: (req) => req.household.id, // your app's Subject mapping
+  onUnavailable: 'closed', // the plugin-wide default; routes may override
+});
+
+// Read feature: an outage shouldn't block reads, so fail open.
+app.get('/reports/export', {
+  preHandler: [app.requireEntitlement('export', { onUnavailable: 'open' })],
+  handler: async (req) => buildExportReport(req.entitlements!),
+});
+
+// Payments-adjacent write: an outage means we can't confirm entitlement,
+// so fail closed rather than risk letting an unpaid write through.
+app.post('/invoices/send', {
+  preHandler: [
+    app.requireEntitlement('send_invoices', { onUnavailable: 'closed' }),
+  ],
+  handler: async (req) => sendInvoice(req.body),
+});
+
+// Limit check: the consumer app owns metering (billing only compares).
+app.post('/emails/send', {
+  preHandler: [
+    app.requireWithinLimit(
+      'emails_per_month',
+      (req) => req.org.emailsSentThisMonth,
+    ),
+  ],
+  handler: async (req) => sendEmail(req.body),
+});
+```
+
+Decision outcomes:
+
+- Entitlements resolve (fresh or stale) → decided on content: feature
+  truthy, or usage under the limit → allow (`request.entitlements`
+  decorated); otherwise `403 entitlement_denied`.
+- Billing unreachable (network failure, or no cached value to fall back
+  on) → `onUnavailable: 'open'` allows the request through; `'closed'`
+  returns `503 billing_unavailable`.
+- A 4xx from the API (bad key, malformed subject) is misconfiguration, not
+  an outage — always denied (`403 billing_misconfigured`) regardless of
+  `onUnavailable`, so fail-open can't mask a broken integration.
+
+Choosing a policy: `'closed'` for anything payments-adjacent or otherwise
+risky to let through unchecked; `'open'` for ordinary reads where a
+billing outage shouldn't take down an unrelated feature.
+
+The framework-agnostic decision function (`checkEntitlement` from
+`./guard.js`) is exported separately for building adapters to other
+frameworks.
+
+## Behavior
+
+- `getEntitlements(subjectId)` caches per-subject for `entitlementsTtlMs`
+  (default 5000ms). Within the TTL it never hits the network. Past the TTL
+  it refetches; if the API is unreachable or returns a 5xx and a cached
+  value exists, it returns that value with `stale: true` instead of
+  throwing. It only throws when there's no cached value, or on a 4xx (bad
+  key, validation) — staleness never masks misconfiguration.
+- `createCheckout`, `portalUrl`, and `getSubscription` always call the API
+  and throw `BillingApiError` on any failure.
+- Every failure is a `BillingApiError` with `status` and `code`. Network
+  failures use `status: 0, code: 'network_error'` so callers can tell
+  "billing is unreachable" apart from "request was denied".

package/dist/chunk-3OSJ6UJT.js

@@ -0,0 +1,495 @@
+// ../shared-types/src/admin.ts
+import { z as z5 } from "zod";
+
+// ../shared-types/src/event-log.ts
+import { z } from "zod";
+var eventStatusSchema = z.enum([
+  "received",
+  "processed",
+  "failed",
+  "dead_letter",
+  "discarded"
+]);
+var subscriptionStateSchema = z.enum([
+  "trialing",
+  "active",
+  "past_due",
+  "canceled",
+  "unpaid"
+]);
+var adminEventSummarySchema = z.object({
+  id: z.string(),
+  projectId: z.string(),
+  providerEventId: z.string(),
+  type: z.string(),
+  status: eventStatusSchema,
+  attempts: z.number(),
+  lastError: z.string().nullable(),
+  errorSignature: z.string().nullable(),
+  receivedAt: z.iso.datetime(),
+  processedAt: z.iso.datetime().nullable(),
+  // event_log has no subject/customer reference column (sprint 24's
+  // repo-drizzle-subjects.ts documents the same gap the other direction) —
+  // derived from the raw Stripe payload's well-known `data.object.customer`
+  // path, so this is null for any non-Stripe-shaped payload.
+  subjectRef: z.string().nullable()
+});
+var adminEventDetailSchema = adminEventSummarySchema.extend({
+  payload: z.record(z.string(), z.unknown()),
+  discardReason: z.string().nullable(),
+  discardedBy: z.string().nullable(),
+  discardedAt: z.iso.datetime().nullable()
+});
+var signatureCountSchema = z.object({
+  signature: z.string(),
+  count: z.number()
+});
+var listEventsResponseSchema = z.object({
+  events: z.array(adminEventSummarySchema),
+  total: z.number(),
+  limit: z.number(),
+  offset: z.number(),
+  signatureCounts: z.array(signatureCountSchema)
+});
+var wouldApplySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("create"), to: subscriptionStateSchema }),
+  z.object({
+    kind: z.literal("transition"),
+    from: subscriptionStateSchema,
+    to: subscriptionStateSchema
+  }),
+  z.object({ kind: z.literal("stale") }),
+  z.object({
+    kind: z.literal("invalid"),
+    from: subscriptionStateSchema,
+    to: subscriptionStateSchema
+  }),
+  z.object({ kind: z.literal("unknown_subscription") }),
+  z.object({ kind: z.literal("noop"), reason: z.string() }),
+  z.object({ kind: z.literal("error"), reason: z.string() })
+]);
+var dryRunReplayResponseSchema = z.object({
+  event: adminEventDetailSchema,
+  current: z.object({
+    state: subscriptionStateSchema,
+    lastEventAt: z.iso.datetime().nullable()
+  }).nullable(),
+  wouldApply: wouldApplySchema
+});
+var replayOutcomeSchema = z.enum([
+  "created",
+  "transitioned",
+  "stale",
+  "noop",
+  "invalid",
+  "unknown_subscription",
+  "already_processed",
+  "error"
+]);
+var replayResponseSchema = z.object({
+  outcome: replayOutcomeSchema
+});
+var discardEventRequestSchema = z.object({
+  actor: z.string().min(1),
+  reason: z.string()
+});
+var replayGroupCursorSchema = z.object({
+  receivedAt: z.iso.datetime(),
+  id: z.string()
+});
+var replayGroupRequestSchema = z.object({
+  projectId: z.string().min(1),
+  cursor: replayGroupCursorSchema.optional(),
+  limit: z.number().int().positive().optional()
+}).and(
+  z.union([
+    z.object({ errorSignature: z.string().min(1) }),
+    z.object({ all: z.literal(true) })
+  ])
+);
+var replayGroupOutcomeEntrySchema = z.object({
+  eventId: z.string(),
+  outcome: replayOutcomeSchema
+});
+var replayGroupResponseSchema = z.object({
+  outcomes: z.array(replayGroupOutcomeEntrySchema),
+  // Keyed by ProcessOutcome, but zod v4's record needs .partial() semantics
+  // for an exhaustive enum key type, so this stays a plain string map — the
+  // set of possible keys is still exactly replayOutcomeSchema's members.
+  counts: z.record(z.string(), z.number()),
+  // This call's batch (its own limit, or BULK_REPLAY_CAP by default) hit its
+  // ceiling: more matching events remain beyond what was just replayed.
+  // Paging with nextCursor continues; a non-paging caller reads this the
+  // same way it always has, as "replay again to finish draining it."
+  truncated: z.boolean(),
+  nextCursor: replayGroupCursorSchema.nullable()
+});
+
+// ../shared-types/src/entitlements.ts
+import { z as z3 } from "zod";
+
+// ../shared-types/src/subscriptions.ts
+import { z as z2 } from "zod";
+var subscriptionStatusSchema = z2.enum([
+  "trialing",
+  "active",
+  "past_due",
+  "grace",
+  "canceled",
+  "unpaid",
+  "none"
+]);
+var activeSubscriptionViewSchema = z2.object({
+  state: subscriptionStatusSchema.exclude(["none"]),
+  planKey: z2.string(),
+  currentPeriodEnd: z2.iso.datetime(),
+  cancelAtPeriodEnd: z2.boolean()
+});
+var noSubscriptionViewSchema = z2.object({
+  state: z2.literal("none")
+});
+var subscriptionViewSchema = z2.discriminatedUnion("state", [
+  activeSubscriptionViewSchema,
+  noSubscriptionViewSchema
+]);
+
+// ../shared-types/src/entitlements.ts
+var entitlementSourcesSchema = z3.object({
+  features: z3.record(z3.string(), z3.enum(["subscription", "override"])),
+  limits: z3.record(z3.string(), z3.enum(["subscription", "override"]))
+});
+var entitlementsResponseSchema = z3.object({
+  plan: z3.string().nullable(),
+  features: z3.record(z3.string(), z3.boolean()),
+  limits: z3.record(z3.string(), z3.number()),
+  status: subscriptionStatusSchema,
+  source: z3.enum(["subscription", "override", "none"]),
+  sources: entitlementSourcesSchema
+});
+
+// ../shared-types/src/overrides.ts
+import { z as z4 } from "zod";
+var overrideKindSchema = z4.enum(["comp", "extend", "revoke"]);
+var overrideTargetSchema = z4.discriminatedUnion("type", [
+  z4.object({ type: z4.literal("feature"), feature: z4.string().min(1) }),
+  z4.object({
+    type: z4.literal("limit"),
+    limit: z4.string().min(1),
+    value: z4.number()
+  })
+]);
+var createOverrideRequestSchema = z4.object({
+  subjectId: z4.string().min(1),
+  kind: overrideKindSchema,
+  target: overrideTargetSchema,
+  actor: z4.string().min(1),
+  reason: z4.string().min(4),
+  expiresAt: z4.iso.datetime().optional()
+});
+var createBulkOverrideRequestSchema = z4.object({
+  subjectId: z4.string().min(1),
+  kind: overrideKindSchema,
+  targets: z4.array(overrideTargetSchema).min(1),
+  actor: z4.string().min(1),
+  reason: z4.string().min(4),
+  expiresAt: z4.iso.datetime().optional()
+});
+var overrideRecordSchema = z4.object({
+  id: z4.string(),
+  subjectId: z4.string(),
+  kind: overrideKindSchema,
+  target: overrideTargetSchema,
+  actor: z4.string(),
+  reason: z4.string(),
+  expiresAt: z4.iso.datetime().nullable(),
+  createdAt: z4.iso.datetime()
+});
+var bulkOverrideResponseSchema = z4.object({
+  overrides: z4.array(overrideRecordSchema)
+});
+var listOverridesResponseSchema = z4.object({
+  overrides: z4.array(overrideRecordSchema),
+  total: z4.number(),
+  limit: z4.number(),
+  offset: z4.number()
+});
+
+// ../shared-types/src/admin.ts
+var stateCountsSchema = z5.object({
+  trialing: z5.number(),
+  active: z5.number(),
+  past_due: z5.number(),
+  grace: z5.number(),
+  canceled: z5.number(),
+  unpaid: z5.number()
+});
+var dashboardMetricsSchema = z5.object({
+  mrrCents: z5.number(),
+  mrrPrevCents: z5.number(),
+  subjectsCount: z5.number(),
+  states: stateCountsSchema,
+  deadLetterDepth: z5.number(),
+  oldestUnprocessedSec: z5.number().nullable(),
+  driftCount: z5.number()
+});
+var projectMetricsSchema = dashboardMetricsSchema.extend({
+  projectId: z5.string(),
+  projectKey: z5.string(),
+  projectName: z5.string(),
+  subjectType: z5.string(),
+  environment: z5.enum(["test", "live"]),
+  envLocked: z5.boolean(),
+  mrrSeries: z5.array(z5.number())
+});
+var adminMetricsResponseSchema = z5.object({
+  ecosystem: dashboardMetricsSchema,
+  // Shared x-axis labels for every project's mrrSeries (same calendar
+  // months across the ecosystem) — empty when no project has snapshots yet.
+  monthLabels: z5.array(z5.string()),
+  projects: z5.array(projectMetricsSchema)
+});
+var adminEventsListResponseSchema = z5.object({
+  events: z5.array(adminEventSummarySchema),
+  nextCursor: z5.string().nullable(),
+  approxTotal: z5.number(),
+  signatureCounts: z5.array(signatureCountSchema).optional()
+});
+var adminEventDetailResponseSchema = z5.object({
+  event: adminEventDetailSchema,
+  transition: z5.object({
+    current: z5.object({
+      state: subscriptionStatusSchema.exclude(["grace", "none"]),
+      lastEventAt: z5.iso.datetime().nullable()
+    }).nullable(),
+    wouldApply: wouldApplySchema
+  })
+});
+var adminSubjectSchema = z5.object({
+  id: z5.string(),
+  subjectType: z5.string(),
+  externalId: z5.string(),
+  providerCustomerId: z5.string().nullable()
+});
+var featureGrantsSchema = z5.record(
+  z5.string(),
+  z5.union([z5.boolean(), z5.number()])
+);
+var adminSubjectSubscriptionPlanSchema = z5.object({
+  key: z5.string(),
+  featureGrants: featureGrantsSchema,
+  priceInterval: z5.enum(["month", "year"]).nullable()
+});
+var adminSubjectLookupResponseSchema = z5.object({
+  subject: adminSubjectSchema,
+  entitlements: entitlementsResponseSchema,
+  recentEvents: z5.array(adminEventSummarySchema),
+  activeOverrides: z5.array(overrideRecordSchema),
+  subscriptionPlan: adminSubjectSubscriptionPlanSchema.nullable()
+});
+var adminPriceSchema = z5.object({
+  id: z5.string(),
+  interval: z5.enum(["month", "year"]),
+  currency: z5.string(),
+  unitAmountCents: z5.number(),
+  syncStatus: z5.enum(["synced", "pending", "drifted"]),
+  syncedUnitAmountCents: z5.number().nullable()
+});
+var adminPlanSchema = z5.object({
+  id: z5.string(),
+  key: z5.string(),
+  name: z5.string(),
+  featureGrants: featureGrantsSchema,
+  activeSubscriptions: z5.number(),
+  prices: z5.array(adminPriceSchema)
+});
+var adminPlansResponseSchema = z5.object({
+  project: z5.object({
+    statementDescriptor: z5.string().nullable(),
+    statementDescriptorPrefix: z5.string().nullable()
+  }),
+  plans: z5.array(adminPlanSchema)
+});
+var adminProviderResponseSchema = z5.object({
+  projectId: z5.string(),
+  providerKind: z5.string(),
+  environment: z5.enum(["test", "live"]),
+  envLocked: z5.boolean(),
+  secretKeyMasked: z5.string().nullable(),
+  publishableKeyMasked: z5.string().nullable(),
+  webhookEndpoint: z5.string(),
+  webhookSigningConfigured: z5.boolean(),
+  defaultPortalReturnUrl: z5.string().nullable()
+});
+var adminAuditEntrySchema = overrideRecordSchema.extend({
+  projectId: z5.string()
+});
+var adminAuditResponseSchema = z5.object({
+  entries: z5.array(adminAuditEntrySchema),
+  nextCursor: z5.string().nullable(),
+  approxTotal: z5.number()
+});
+var adminThroughputResponseSchema = z5.object({
+  days: z5.array(z5.string()),
+  processed: z5.array(z5.number()),
+  failed: z5.array(z5.number())
+});
+var adminPlanMixResponseSchema = z5.object({
+  months: z5.array(z5.string()),
+  plans: z5.array(z5.object({ key: z5.string(), name: z5.string() })),
+  stacks: z5.array(z5.array(z5.number()))
+});
+var adminDeadLetterGroupSchema = z5.object({
+  projectId: z5.string(),
+  signature: z5.string(),
+  count: z5.number(),
+  sampleEventId: z5.string(),
+  firstReceivedAt: z5.iso.datetime(),
+  lastReceivedAt: z5.iso.datetime()
+});
+var adminDeadLetterGroupsResponseSchema = z5.object({
+  groups: z5.array(adminDeadLetterGroupSchema)
+});
+var adminProjectDashboardResponseSchema = z5.object({
+  metrics: projectMetricsSchema,
+  monthLabels: z5.array(z5.string()),
+  providerKind: z5.string(),
+  plans: z5.array(adminPlanSchema)
+});
+
+// ../shared-types/src/checkout.ts
+import { z as z6 } from "zod";
+var checkoutRequestSchema = z6.object({
+  planKey: z6.string(),
+  subjectId: z6.string(),
+  successUrl: z6.url(),
+  cancelUrl: z6.url(),
+  email: z6.email().optional()
+});
+var checkoutResponseSchema = z6.object({
+  url: z6.url()
+});
+var portalRequestSchema = z6.object({
+  subjectId: z6.string(),
+  returnUrl: z6.url()
+});
+var portalResponseSchema = z6.object({
+  url: z6.url()
+});
+
+// ../shared-types/src/projects.ts
+import { z as z7 } from "zod";
+var registerProjectRequestSchema = z7.object({
+  key: z7.string().trim().min(1, "is required"),
+  name: z7.string().trim().min(1, "is required"),
+  subjectType: z7.string().trim().min(1, "is required"),
+  environment: z7.enum(["test", "live"], 'must be "test" or "live"'),
+  envLocked: z7.boolean().optional(),
+  providerKind: z7.string().trim().min(1, "is required"),
+  providerSecretKeyRef: z7.string().optional(),
+  providerPublishableKeyRef: z7.string().optional(),
+  providerPortalConfigRef: z7.string().optional(),
+  statementDescriptor: z7.string().optional(),
+  statementDescriptorPrefix: z7.string().optional(),
+  graceDays: z7.number().min(0, "must be >= 0").optional(),
+  defaultPortalReturnUrl: z7.url().optional()
+}).superRefine((input, ctx) => {
+  if (!input.statementDescriptor && !input.statementDescriptorPrefix) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["statementDescriptor"],
+      message: "statementDescriptor or statementDescriptorPrefix is required"
+    });
+  }
+});
+
+// ../shared-types/src/errors.ts
+import { z as z8 } from "zod";
+var errorEnvelopeSchema = z8.object({
+  error: z8.object({
+    code: z8.string(),
+    message: z8.string()
+  })
+});
+
+// ../shared-types/src/webhook-secret.ts
+import { z as z9 } from "zod";
+var webhookSigningSecretSchema = z9.string().regex(/^whsec_.+/, "must be a non-empty whsec_-prefixed string");
+
+// ../shared-types/src/portal-return-url.ts
+import { z as z10 } from "zod";
+var portalReturnUrlSchema = z10.url();
+
+// src/errors.ts
+var BillingApiError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.name = "BillingApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
+async function errorFromResponse(response) {
+  let code = "unknown_error";
+  let message = `Request failed with status ${response.status}`;
+  try {
+    const body = await response.json();
+    const parsed = errorEnvelopeSchema.safeParse(body);
+    if (parsed.success) {
+      code = parsed.data.error.code;
+      message = parsed.data.error.message;
+    }
+  } catch {
+  }
+  return new BillingApiError(response.status, code, message);
+}
+function networkError(cause) {
+  const message = cause instanceof Error ? cause.message : "Network request failed";
+  return new BillingApiError(0, "network_error", message);
+}
+function invalidResponseError(message) {
+  return new BillingApiError(502, "invalid_response", message);
+}
+
+// src/guard.ts
+function isMisconfiguration(err) {
+  return err instanceof BillingApiError && err.status >= 400 && err.status < 500;
+}
+function decideOnContent(entitlements, feature, limit) {
+  if (feature !== void 0) {
+    return entitlements.features[feature] ? { decision: "allow", entitlements } : { decision: "deny", reason: `Feature "${feature}" is not entitled` };
+  }
+  if (limit !== void 0) {
+    const max = entitlements.limits[limit.key];
+    return max !== void 0 && limit.usage < max ? { decision: "allow", entitlements } : { decision: "deny", reason: `Limit "${limit.key}" has been reached` };
+  }
+  return { decision: "allow", entitlements };
+}
+async function checkEntitlement(input) {
+  const { client, subjectId, feature, limit, onUnavailable } = input;
+  let entitlements;
+  try {
+    entitlements = await client.getEntitlements(subjectId);
+  } catch (err) {
+    if (isMisconfiguration(err)) {
+      const message = err instanceof Error ? err.message : "Billing request was rejected";
+      return { decision: "deny", reason: message, misconfigured: true };
+    }
+    return onUnavailable === "open" ? { decision: "unavailable-allow" } : { decision: "unavailable-deny", reason: "Billing is unavailable" };
+  }
+  return decideOnContent(entitlements, feature, limit);
+}
+
+export {
+  subscriptionViewSchema,
+  entitlementsResponseSchema,
+  checkoutResponseSchema,
+  portalResponseSchema,
+  BillingApiError,
+  errorFromResponse,
+  networkError,
+  invalidResponseError,
+  checkEntitlement
+};
+//# sourceMappingURL=chunk-3OSJ6UJT.js.map