founder-schema 0.11.0 → 0.12.0

package/dist/domains/billing/billing.d.ts.map

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

package/dist/domains/billing/billing.js

@@ -0,0 +1,393 @@
+/**
+ * founder-schema: buying, paying, invoices, refunds and coupons (0.12.0)
+ *
+ *   POST /api/v1/billing/quote               quoteBodySchema -> quoteSchema
+ *   POST /api/v1/billing/orders              createOrderBodySchema -> createOrderResponseSchema
+ *   GET  /api/v1/billing/orders/:orderId     orderStateSchema (polled while "processing")
+ *   POST /api/v1/billing/orders/:orderId/confirm  confirmOrderBodySchema -> orderStateSchema
+ *   GET  /api/v1/billing/payments            paymentPageSchema (mine)
+ *   GET  /api/v1/billing/payments/:orderId   paymentDetailSchema (mine, with the invoice)
+ *
+ *   Staff (by the ability: support reads; managers refund and run coupons):
+ *   GET  /api/v1/staff/payments              staffPaymentsQuerySchema -> staffPaymentPageSchema
+ *   GET  /api/v1/staff/payments/:orderId     staffPaymentDetailSchema
+ *   POST /api/v1/staff/payments/:orderId/refund   refundPaymentBodySchema -> staffPaymentDetailSchema
+ *   GET  /api/v1/staff/coupons               couponListSchema
+ *   POST /api/v1/staff/coupons               createCouponBodySchema -> couponSchema
+ *   PATCH /api/v1/staff/coupons/:couponId    updateCouponBodySchema -> couponSchema
+ *   PUT  /api/v1/members/:memberId/membership    setMembershipBodySchema -> memberDetailSchema
+ *
+ * THE ONE RULE: THE SERVER PRICES, THE CLIENT CHOOSES. A request names what it
+ * wants (an item) and maybe a coupon CODE; it never names an amount. Every
+ * amount here is the server's, in integer paise, GST included.
+ *
+ * TWO PATHS IN, ONE GRANT. A payment reaches the server from the browser the
+ * moment checkout returns (`confirm`) and from the gateway's webhook. Either
+ * grants; the second is a no-op. So a member who closes the tab is still
+ * granted, and `confirm` failing never means "not paid": the web says
+ * "processing" and polls the order.
+ *
+ * GST: the company is registered, every captured payment gets a tax invoice,
+ * every refund a credit note. Where the buyer is decides the tax: in the
+ * supplier's state CGST + SGST, elsewhere IGST. So checkout asks for the state.
+ *
+ * @module founder-schema/domains/billing
+ */
+import { z } from 'zod';
+import { emptyStringToUndefined, objectIdSchema, paginationQuerySchema, } from '../../core/common.js';
+import { BILLING_REASON_MAX, BILLING_REASON_MIN, COUPON_CODE_MAX, COUPON_CODE_MIN, COUPON_LABEL_MAX, } from '../../core/limits.js';
+import { paginatedSchema } from '../../core/responses.js';
+import { VALIDATION_MESSAGE } from '../../core/validation.js';
+import { paiseSchema, planPeriodSchema, planTierSchema } from '../membership/membership.js';
+import { billingDetailsSchema, gstStateCodeSchema } from './gst.js';
+export { billingDetailsSchema, GST_RATE_PERCENT, GST_STATE_CODE_VALUES, GST_STATES, gstinChecksumValid, gstinSchema, gstStateCodeSchema, gstStateName, } from './gst.js';
+// ─── What can be bought ──────────────────────────────────────────────────────
+/** ⚠ Stored on every order: append only. */
+export const PURCHASE_KIND_VALUES = ['membership', 'plan', 'upgrade'];
+export const purchaseKindSchema = z.enum(PURCHASE_KIND_VALUES);
+/**
+ * The thing asked for.
+ *
+ *   membership  Rs 99, once
+ *   plan        a month or a year of Premium or Business, appended
+ *   upgrade     the Premium time left, turned into Business, for the difference
+ */
+export const purchaseItemSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('membership') }),
+    z.object({ kind: z.literal('plan'), tier: planTierSchema, period: planPeriodSchema }),
+    z.object({ kind: z.literal('upgrade') }),
+]);
+/** A coupon code as typed: letters, digits, hyphens; compared upper-case. */
+export const couponCodeSchema = z
+    .string()
+    .trim()
+    .min(COUPON_CODE_MIN)
+    .max(COUPON_CODE_MAX)
+    .regex(/^[A-Za-z0-9-]+$/, VALIDATION_MESSAGE.couponCodeInvalid)
+    .transform((v) => v.toUpperCase());
+// ─── Quote ───────────────────────────────────────────────────────────────────
+/**
+ * The tax inside a total. `taxable + cgst + sgst + igst = total`; either
+ * CGST + SGST (buyer in the supplier's state) or IGST, never both.
+ */
+export const taxSplitSchema = z.object({
+    ratePercent: z.number().int().positive(),
+    taxable: paiseSchema,
+    cgst: paiseSchema,
+    sgst: paiseSchema,
+    igst: paiseSchema,
+    total: paiseSchema,
+});
+/** `POST /billing/quote`. The state is optional: without it, no tax split. */
+export const quoteBodySchema = z.object({
+    item: purchaseItemSchema,
+    couponCode: couponCodeSchema.optional(),
+    stateCode: gstStateCodeSchema.optional(),
+});
+/** What a plan or an upgrade would do to the plan, priced now. */
+export const planEffectSchema = z.object({
+    tier: planTierSchema,
+    /** When this purchase's time starts (later than now when it waits its turn). */
+    startsAt: z.iso.datetime(),
+    endsAt: z.iso.datetime(),
+    /** For an upgrade: the days of Premium turned into Business. */
+    upgradedDays: z.number().int().positive().nullable(),
+});
+export const quoteSchema = z.object({
+    item: purchaseItemSchema,
+    /** "Membership", "Premium, 1 month", "Upgrade to Business": the server's words. */
+    title: z.string(),
+    listPrice: paiseSchema,
+    discount: paiseSchema,
+    /** What would be charged. Zero for a free-membership coupon: no checkout at all. */
+    total: paiseSchema,
+    coupon: z.object({ code: z.string(), label: z.string() }).nullable(),
+    /** Null for a membership. */
+    plan: planEffectSchema.nullable(),
+    /** Null without a state. */
+    tax: taxSplitSchema.nullable(),
+    refundWindowDays: z.number().int().positive(),
+});
+// ─── Orders ──────────────────────────────────────────────────────────────────
+/**
+ * Where an order stands. ⚠ Stored: append only.
+ *
+ *   created         checkout open, nothing paid yet
+ *   paid            captured and granted; has an invoice
+ *   granted_free    a free coupon: granted with no payment and no invoice
+ *   expired         not paid within `ORDER_TTL_MINUTES`
+ *   refund_pending  staff refunded it; the gateway is returning the money
+ *   refunded        the money is back; has a credit note
+ *   refund_failed   the gateway could not return it; staff act from its dashboard
+ */
+export const ORDER_STATUS_VALUES = [
+    'created',
+    'paid',
+    'granted_free',
+    'expired',
+    'refund_pending',
+    'refunded',
+    'refund_failed',
+];
+export const orderStatusSchema = z.enum(ORDER_STATUS_VALUES);
+/**
+ * `POST /billing/orders`. Billing details are required for anything paid (the
+ * invoice needs a place of supply): the server refuses a paid order without
+ * them (`billing.stateCode`, VALIDATION_ERROR). A free coupon issues no
+ * invoice, so it needs none (0.12.0).
+ */
+export const createOrderBodySchema = z.object({
+    item: purchaseItemSchema,
+    couponCode: couponCodeSchema.optional(),
+    billing: billingDetailsSchema.optional(),
+});
+/**
+ * Either done (a free coupon granted at once) or a checkout to open. The
+ * checkout fields are Razorpay Checkout's own options; identity (name, email,
+ * phone) is the server's, never typed by the caller.
+ */
+export const createOrderResponseSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('granted'), orderId: objectIdSchema }),
+    z.object({
+        status: z.literal('checkout'),
+        orderId: objectIdSchema,
+        expiresAt: z.iso.datetime(),
+        checkout: z.object({
+            keyId: z.string().min(1),
+            razorpayOrderId: z.string().min(1),
+            amount: paiseSchema,
+            currency: z.literal('INR'),
+            /** The merchant name on the dialog. */
+            name: z.string(),
+            /** What is being bought, under the name. */
+            description: z.string(),
+            prefill: z.object({
+                name: z.string(),
+                email: z.string(),
+                contact: z.string().optional(),
+            }),
+        }),
+    }),
+]);
+export const orderParamsSchema = z.object({ orderId: objectIdSchema });
+/** What Razorpay Checkout's `handler` hands back, as it names it. */
+export const confirmOrderBodySchema = z.object({
+    razorpayOrderId: z.string().min(1).max(64),
+    razorpayPaymentId: z.string().min(1).max(64),
+    razorpaySignature: z.string().min(1).max(256),
+});
+/** An order as its buyer polls it. */
+export const orderStateSchema = z.object({
+    orderId: objectIdSchema,
+    item: purchaseItemSchema,
+    status: orderStatusSchema,
+    /**
+     * The money was taken but what it bought could not be applied (bought
+     * twice in two tabs, the plan changed while paying): it is refunded in
+     * full, by itself. The client says so instead of "done".
+     */
+    notApplied: z.boolean(),
+});
+// ─── Payments, invoices, credit notes ────────────────────────────────────────
+/** A party on an invoice. The supplier always has a GSTIN on a real invoice; a buyer, only on B2B. */
+export const invoicePartySchema = z.object({
+    name: z.string(),
+    address: z.string().nullable(),
+    gstin: z.string().nullable(),
+    stateCode: gstStateCodeSchema,
+    stateName: z.string(),
+});
+/** A tax invoice, frozen when the payment was captured. */
+export const invoiceSchema = z.object({
+    /** e.g. `FC/26-27/000123`: sequential within a financial year, at most 16 characters. */
+    number: z.string().max(16),
+    issuedAt: z.iso.datetime(),
+    /**
+     * Issued where the supplier's GSTIN is not configured (dev, Razorpay test
+     * mode): marked "TEST: not a tax invoice". Never true in production.
+     */
+    test: z.boolean(),
+    supplier: invoicePartySchema,
+    buyer: invoicePartySchema,
+    /** B2B with the buyer's GSTIN, B2C without. */
+    kind: z.enum(['b2b', 'b2c']),
+    /** The service's accounting code (SAC). */
+    sac: z.string(),
+    description: z.string(),
+    tax: taxSplitSchema,
+    /** Always false: these services are never under reverse charge. */
+    reverseCharge: z.literal(false),
+    razorpayPaymentId: z.string(),
+});
+/** A refund's credit note, against its invoice. */
+export const creditNoteSchema = z.object({
+    /** e.g. `FCCN/26-27/00012`: the invoice series + `CN`, sequential within a financial year. */
+    number: z.string().max(16),
+    issuedAt: z.iso.datetime(),
+    invoiceNumber: z.string(),
+    tax: taxSplitSchema,
+});
+/** One purchase in a member's history. Only settled orders are listed, never an abandoned checkout. */
+export const paymentSummarySchema = z.object({
+    id: objectIdSchema,
+    item: purchaseItemSchema,
+    title: z.string(),
+    total: paiseSchema,
+    status: orderStatusSchema,
+    /** When it was captured, or granted for a free coupon. */
+    paidAt: z.iso.datetime(),
+    invoiceNumber: z.string().nullable(),
+    /** Until when a refund may be asked for; null once refunded or for a free coupon. */
+    refundableUntil: z.iso.datetime().nullable(),
+});
+export const paymentPageSchema = paginatedSchema(paymentSummarySchema);
+export const paymentDetailSchema = paymentSummarySchema.extend({
+    listPrice: paiseSchema,
+    discount: paiseSchema,
+    coupon: z.object({ code: z.string(), label: z.string() }).nullable(),
+    invoice: invoiceSchema.nullable(),
+    creditNote: creditNoteSchema.nullable(),
+    refundedAt: z.iso.datetime().nullable(),
+});
+// ─── Staff: payments and refunds ─────────────────────────────────────────────
+/** Who paid, as they are now, so staff can find them. Email only for a role that may read it. */
+export const payerSchema = z.object({
+    id: objectIdSchema,
+    displayName: z.string(),
+    email: z.string().nullable(),
+});
+export const staffPaymentsQuerySchema = paginationQuerySchema.extend({
+    status: orderStatusSchema.optional(),
+    memberId: objectIdSchema.optional(),
+    /** Only the ones a person must act on (`needsAction` below). */
+    needsAction: z.preprocess(emptyStringToUndefined, z.stringbool().default(false)),
+});
+export const staffPaymentSummarySchema = paymentSummarySchema.extend({
+    payer: payerSchema,
+    /**
+     * A person must act (0.12.0): taken but not applied and not yet refunded
+     * (the automatic refund did not go through), a refund that failed at the
+     * gateway, or an open chargeback.
+     */
+    needsAction: z.boolean(),
+});
+export const staffPaymentPageSchema = paginatedSchema(staffPaymentSummarySchema);
+export const staffPaymentDetailSchema = paymentDetailSchema.extend({
+    payer: payerSchema,
+    razorpay: z.object({
+        orderId: z.string().nullable(),
+        paymentId: z.string().nullable(),
+        refundId: z.string().nullable(),
+    }),
+    /** Why staff refunded it, on record. */
+    refundReason: z.string().nullable(),
+    /**
+     * The money was taken but what it bought could not be applied when it was
+     * captured (they were a member already, the Premium time to upgrade had
+     * run out, past the 3-year cap): refund it. Null when it applied.
+     */
+    grantFailed: z.string().nullable(),
+    /** A chargeback was opened on it (cleared when it is won or closed). */
+    disputedAt: z.iso.datetime().nullable(),
+    /**
+     * What refunds made outside Founder Circle (the Razorpay dashboard) have
+     * already given back of this payment. A Refund here gives back the rest:
+     * `total` less this. 0 when there were none.
+     */
+    refundedOutside: paiseSchema,
+    /**
+     * Payments captured on this order other than the one that settled it (a
+     * late authorisation, a second Checkout attempt): each is refunded by
+     * itself; `refunded: false` means that refund has not gone through yet and
+     * the payment needs a person.
+     */
+    strayPayments: z.array(z.object({
+        paymentId: z.string(),
+        amount: paiseSchema,
+        refunded: z.boolean(),
+        at: z.iso.datetime(),
+    })),
+    viewer: z.object({
+        /** Paid, within the window, not their own, and the asker may refund. */
+        canRefund: z.boolean(),
+    }),
+});
+const reasonSchema = z.string().trim().min(BILLING_REASON_MIN).max(BILLING_REASON_MAX);
+/** `POST /staff/payments/:orderId/refund`. The reason is on the audit record. */
+export const refundPaymentBodySchema = z.object({ reason: reasonSchema });
+/**
+ * `PUT /members/:memberId/membership`: grant (a partner, a press account) or
+ * revoke (a fake or duplicate account holding a founding place). A paid one
+ * is never revoked: refund its payment.
+ */
+export const setMembershipBodySchema = z.object({
+    granted: z.boolean(),
+    reason: reasonSchema,
+});
+// ─── Staff: coupons ──────────────────────────────────────────────────────────
+/** What a coupon is good for. A percent coupon names what it applies to. */
+export const COUPON_TARGET_VALUES = ['membership', 'premium', 'business'];
+export const couponTargetSchema = z.enum(COUPON_TARGET_VALUES);
+/**
+ * ⚠ Stored: append only.
+ *
+ *   free_membership  the membership at Rs 0; `founding` numbers its holders
+ *                    ("Founding member #N")
+ *   percent_off      a share off the listed price of what it applies to
+ */
+export const couponBenefitSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('free_membership'), founding: z.boolean() }),
+    z.object({
+        kind: z.literal('percent_off'),
+        percent: z.number().int().min(1).max(90),
+        appliesTo: z
+            .array(couponTargetSchema)
+            .min(1)
+            .max(COUPON_TARGET_VALUES.length)
+            .refine((list) => new Set(list).size === list.length, {
+            error: VALIDATION_MESSAGE.couponTargetsDuplicate,
+        }),
+    }),
+]);
+export const couponSchema = z.object({
+    id: objectIdSchema,
+    code: z.string(),
+    label: z.string(),
+    benefit: couponBenefitSchema,
+    /** Redemptions allowed in all; null is no cap. */
+    max: z.number().int().positive().nullable(),
+    /** Redemptions in force (a revoked founding place frees one). */
+    used: z.number().int().nonnegative(),
+    active: z.boolean(),
+    validFrom: z.iso.datetime().nullable(),
+    validUntil: z.iso.datetime().nullable(),
+    createdAt: z.iso.datetime(),
+});
+/** Never paged: coupons are few. Newest first. */
+export const couponListSchema = z.object({ items: z.array(couponSchema) });
+export const couponParamsSchema = z.object({ couponId: objectIdSchema });
+const windowValid = (body) => !body.validFrom || !body.validUntil || Date.parse(body.validFrom) < Date.parse(body.validUntil);
+export const createCouponBodySchema = z
+    .object({
+    code: couponCodeSchema,
+    label: z.string().trim().min(2).max(COUPON_LABEL_MAX),
+    benefit: couponBenefitSchema,
+    max: z.number().int().positive().nullable(),
+    validFrom: z.iso.datetime().nullable().optional(),
+    validUntil: z.iso.datetime().nullable().optional(),
+})
+    .refine(windowValid, { path: ['validUntil'], error: VALIDATION_MESSAGE.couponWindowInvalid });
+/**
+ * What may change on a live coupon. The code and the benefit never change: a
+ * redemption is a record of what a code gave when it was used.
+ */
+export const updateCouponBodySchema = z
+    .object({
+    label: z.string().trim().min(2).max(COUPON_LABEL_MAX).optional(),
+    active: z.boolean().optional(),
+    max: z.number().int().positive().nullable().optional(),
+    validFrom: z.iso.datetime().nullable().optional(),
+    validUntil: z.iso.datetime().nullable().optional(),
+})
+    .refine(windowValid, { path: ['validUntil'], error: VALIDATION_MESSAGE.couponWindowInvalid });
+//# sourceMappingURL=billing.js.map

package/dist/domains/billing/billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["../../../src/domains/billing/billing.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * founder-schema: buying, paying, invoices, refunds and coupons (0.12.0)\n *\n *   POST /api/v1/billing/quote               quoteBodySchema -> quoteSchema\n *   POST /api/v1/billing/orders              createOrderBodySchema -> createOrderResponseSchema\n *   GET  /api/v1/billing/orders/:orderId     orderStateSchema (polled while \"processing\")\n *   POST /api/v1/billing/orders/:orderId/confirm  confirmOrderBodySchema -> orderStateSchema\n *   GET  /api/v1/billing/payments            paymentPageSchema (mine)\n *   GET  /api/v1/billing/payments/:orderId   paymentDetailSchema (mine, with the invoice)\n *\n *   Staff (by the ability: support reads; managers refund and run coupons):\n *   GET  /api/v1/staff/payments              staffPaymentsQuerySchema -> staffPaymentPageSchema\n *   GET  /api/v1/staff/payments/:orderId     staffPaymentDetailSchema\n *   POST /api/v1/staff/payments/:orderId/refund   refundPaymentBodySchema -> staffPaymentDetailSchema\n *   GET  /api/v1/staff/coupons               couponListSchema\n *   POST /api/v1/staff/coupons               createCouponBodySchema -> couponSchema\n *   PATCH /api/v1/staff/coupons/:couponId    updateCouponBodySchema -> couponSchema\n *   PUT  /api/v1/members/:memberId/membership    setMembershipBodySchema -> memberDetailSchema\n *\n * THE ONE RULE: THE SERVER PRICES, THE CLIENT CHOOSES. A request names what it\n * wants (an item) and maybe a coupon CODE; it never names an amount. Every\n * amount here is the server's, in integer paise, GST included.\n *\n * TWO PATHS IN, ONE GRANT. A payment reaches the server from the browser the\n * moment checkout returns (`confirm`) and from the gateway's webhook. Either\n * grants; the second is a no-op. So a member who closes the tab is still\n * granted, and `confirm` failing never means \"not paid\": the web says\n * \"processing\" and polls the order.\n *\n * GST: the company is registered, every captured payment gets a tax invoice,\n * every refund a credit note. Where the buyer is decides the tax: in the\n * supplier's state CGST + SGST, elsewhere IGST. So checkout asks for the state.\n *\n * @module founder-schema/domains/billing\n */\n\nimport { z } from 'zod';\nimport {\n  emptyStringToUndefined,\n  objectIdSchema,\n  paginationQuerySchema,\n} from '../../core/common.js';\nimport {\n  BILLING_REASON_MAX,\n  BILLING_REASON_MIN,\n  COUPON_CODE_MAX,\n  COUPON_CODE_MIN,\n  COUPON_LABEL_MAX,\n} from '../../core/limits.js';\nimport { paginatedSchema } from '../../core/responses.js';\nimport { VALIDATION_MESSAGE } from '../../core/validation.js';\nimport { paiseSchema, planPeriodSchema, planTierSchema } from '../membership/membership.js';\nimport { billingDetailsSchema, gstStateCodeSchema } from './gst.js';\n\nexport {\n  type BillingDetails,\n  billingDetailsSchema,\n  GST_RATE_PERCENT,\n  GST_STATE_CODE_VALUES,\n  GST_STATES,\n  type GstStateCode,\n  gstinChecksumValid,\n  gstinSchema,\n  gstStateCodeSchema,\n  gstStateName,\n} from './gst.js';\n\n// ─── What can be bought ──────────────────────────────────────────────────────\n\n/** ⚠ Stored on every order: append only. */\nexport const PURCHASE_KIND_VALUES = ['membership', 'plan', 'upgrade'] as const;\nexport const purchaseKindSchema = z.enum(PURCHASE_KIND_VALUES);\nexport type PurchaseKind = z.infer<typeof purchaseKindSchema>;\n\n/**\n * The thing asked for.\n *\n *   membership  Rs 99, once\n *   plan        a month or a year of Premium or Business, appended\n *   upgrade     the Premium time left, turned into Business, for the difference\n */\nexport const purchaseItemSchema = z.discriminatedUnion('kind', [\n  z.object({ kind: z.literal('membership') }),\n  z.object({ kind: z.literal('plan'), tier: planTierSchema, period: planPeriodSchema }),\n  z.object({ kind: z.literal('upgrade') }),\n]);\nexport type PurchaseItem = z.infer<typeof purchaseItemSchema>;\n\n/** A coupon code as typed: letters, digits, hyphens; compared upper-case. */\nexport const couponCodeSchema = z\n  .string()\n  .trim()\n  .min(COUPON_CODE_MIN)\n  .max(COUPON_CODE_MAX)\n  .regex(/^[A-Za-z0-9-]+$/, VALIDATION_MESSAGE.couponCodeInvalid)\n  .transform((v) => v.toUpperCase());\n\n// ─── Quote ───────────────────────────────────────────────────────────────────\n\n/**\n * The tax inside a total. `taxable + cgst + sgst + igst = total`; either\n * CGST + SGST (buyer in the supplier's state) or IGST, never both.\n */\nexport const taxSplitSchema = z.object({\n  ratePercent: z.number().int().positive(),\n  taxable: paiseSchema,\n  cgst: paiseSchema,\n  sgst: paiseSchema,\n  igst: paiseSchema,\n  total: paiseSchema,\n});\nexport type TaxSplit = z.infer<typeof taxSplitSchema>;\n\n/** `POST /billing/quote`. The state is optional: without it, no tax split. */\nexport const quoteBodySchema = z.object({\n  item: purchaseItemSchema,\n  couponCode: couponCodeSchema.optional(),\n  stateCode: gstStateCodeSchema.optional(),\n});\nexport type QuoteBody = z.infer<typeof quoteBodySchema>;\n\n/** What a plan or an upgrade would do to the plan, priced now. */\nexport const planEffectSchema = z.object({\n  tier: planTierSchema,\n  /** When this purchase's time starts (later than now when it waits its turn). */\n  startsAt: z.iso.datetime(),\n  endsAt: z.iso.datetime(),\n  /** For an upgrade: the days of Premium turned into Business. */\n  upgradedDays: z.number().int().positive().nullable(),\n});\nexport type PlanEffect = z.infer<typeof planEffectSchema>;\n\nexport const quoteSchema = z.object({\n  item: purchaseItemSchema,\n  /** \"Membership\", \"Premium, 1 month\", \"Upgrade to Business\": the server's words. */\n  title: z.string(),\n  listPrice: paiseSchema,\n  discount: paiseSchema,\n  /** What would be charged. Zero for a free-membership coupon: no checkout at all. */\n  total: paiseSchema,\n  coupon: z.object({ code: z.string(), label: z.string() }).nullable(),\n  /** Null for a membership. */\n  plan: planEffectSchema.nullable(),\n  /** Null without a state. */\n  tax: taxSplitSchema.nullable(),\n  refundWindowDays: z.number().int().positive(),\n});\nexport type Quote = z.infer<typeof quoteSchema>;\n\n// ─── Orders ──────────────────────────────────────────────────────────────────\n\n/**\n * Where an order stands. ⚠ Stored: append only.\n *\n *   created         checkout open, nothing paid yet\n *   paid            captured and granted; has an invoice\n *   granted_free    a free coupon: granted with no payment and no invoice\n *   expired         not paid within `ORDER_TTL_MINUTES`\n *   refund_pending  staff refunded it; the gateway is returning the money\n *   refunded        the money is back; has a credit note\n *   refund_failed   the gateway could not return it; staff act from its dashboard\n */\nexport const ORDER_STATUS_VALUES = [\n  'created',\n  'paid',\n  'granted_free',\n  'expired',\n  'refund_pending',\n  'refunded',\n  'refund_failed',\n] as const;\nexport const orderStatusSchema = z.enum(ORDER_STATUS_VALUES);\nexport type OrderStatus = z.infer<typeof orderStatusSchema>;\n\n/**\n * `POST /billing/orders`. Billing details are required for anything paid (the\n * invoice needs a place of supply): the server refuses a paid order without\n * them (`billing.stateCode`, VALIDATION_ERROR). A free coupon issues no\n * invoice, so it needs none (0.12.0).\n */\nexport const createOrderBodySchema = z.object({\n  item: purchaseItemSchema,\n  couponCode: couponCodeSchema.optional(),\n  billing: billingDetailsSchema.optional(),\n});\nexport type CreateOrderBody = z.infer<typeof createOrderBodySchema>;\n\n/**\n * Either done (a free coupon granted at once) or a checkout to open. The\n * checkout fields are Razorpay Checkout's own options; identity (name, email,\n * phone) is the server's, never typed by the caller.\n */\nexport const createOrderResponseSchema = z.discriminatedUnion('status', [\n  z.object({ status: z.literal('granted'), orderId: objectIdSchema }),\n  z.object({\n    status: z.literal('checkout'),\n    orderId: objectIdSchema,\n    expiresAt: z.iso.datetime(),\n    checkout: z.object({\n      keyId: z.string().min(1),\n      razorpayOrderId: z.string().min(1),\n      amount: paiseSchema,\n      currency: z.literal('INR'),\n      /** The merchant name on the dialog. */\n      name: z.string(),\n      /** What is being bought, under the name. */\n      description: z.string(),\n      prefill: z.object({\n        name: z.string(),\n        email: z.string(),\n        contact: z.string().optional(),\n      }),\n    }),\n  }),\n]);\nexport type CreateOrderResponse = z.infer<typeof createOrderResponseSchema>;\n\nexport const orderParamsSchema = z.object({ orderId: objectIdSchema });\nexport type OrderParams = z.infer<typeof orderParamsSchema>;\n\n/** What Razorpay Checkout's `handler` hands back, as it names it. */\nexport const confirmOrderBodySchema = z.object({\n  razorpayOrderId: z.string().min(1).max(64),\n  razorpayPaymentId: z.string().min(1).max(64),\n  razorpaySignature: z.string().min(1).max(256),\n});\nexport type ConfirmOrderBody = z.infer<typeof confirmOrderBodySchema>;\n\n/** An order as its buyer polls it. */\nexport const orderStateSchema = z.object({\n  orderId: objectIdSchema,\n  item: purchaseItemSchema,\n  status: orderStatusSchema,\n  /**\n   * The money was taken but what it bought could not be applied (bought\n   * twice in two tabs, the plan changed while paying): it is refunded in\n   * full, by itself. The client says so instead of \"done\".\n   */\n  notApplied: z.boolean(),\n});\nexport type OrderState = z.infer<typeof orderStateSchema>;\n\n// ─── Payments, invoices, credit notes ────────────────────────────────────────\n\n/** A party on an invoice. The supplier always has a GSTIN on a real invoice; a buyer, only on B2B. */\nexport const invoicePartySchema = z.object({\n  name: z.string(),\n  address: z.string().nullable(),\n  gstin: z.string().nullable(),\n  stateCode: gstStateCodeSchema,\n  stateName: z.string(),\n});\nexport type InvoiceParty = z.infer<typeof invoicePartySchema>;\n\n/** A tax invoice, frozen when the payment was captured. */\nexport const invoiceSchema = z.object({\n  /** e.g. `FC/26-27/000123`: sequential within a financial year, at most 16 characters. */\n  number: z.string().max(16),\n  issuedAt: z.iso.datetime(),\n  /**\n   * Issued where the supplier's GSTIN is not configured (dev, Razorpay test\n   * mode): marked \"TEST: not a tax invoice\". Never true in production.\n   */\n  test: z.boolean(),\n  supplier: invoicePartySchema,\n  buyer: invoicePartySchema,\n  /** B2B with the buyer's GSTIN, B2C without. */\n  kind: z.enum(['b2b', 'b2c']),\n  /** The service's accounting code (SAC). */\n  sac: z.string(),\n  description: z.string(),\n  tax: taxSplitSchema,\n  /** Always false: these services are never under reverse charge. */\n  reverseCharge: z.literal(false),\n  razorpayPaymentId: z.string(),\n});\nexport type Invoice = z.infer<typeof invoiceSchema>;\n\n/** A refund's credit note, against its invoice. */\nexport const creditNoteSchema = z.object({\n  /** e.g. `FCCN/26-27/00012`: the invoice series + `CN`, sequential within a financial year. */\n  number: z.string().max(16),\n  issuedAt: z.iso.datetime(),\n  invoiceNumber: z.string(),\n  tax: taxSplitSchema,\n});\nexport type CreditNote = z.infer<typeof creditNoteSchema>;\n\n/** One purchase in a member's history. Only settled orders are listed, never an abandoned checkout. */\nexport const paymentSummarySchema = z.object({\n  id: objectIdSchema,\n  item: purchaseItemSchema,\n  title: z.string(),\n  total: paiseSchema,\n  status: orderStatusSchema,\n  /** When it was captured, or granted for a free coupon. */\n  paidAt: z.iso.datetime(),\n  invoiceNumber: z.string().nullable(),\n  /** Until when a refund may be asked for; null once refunded or for a free coupon. */\n  refundableUntil: z.iso.datetime().nullable(),\n});\nexport type PaymentSummary = z.infer<typeof paymentSummarySchema>;\n\nexport const paymentPageSchema = paginatedSchema(paymentSummarySchema);\nexport type PaymentPage = z.infer<typeof paymentPageSchema>;\n\nexport const paymentDetailSchema = paymentSummarySchema.extend({\n  listPrice: paiseSchema,\n  discount: paiseSchema,\n  coupon: z.object({ code: z.string(), label: z.string() }).nullable(),\n  invoice: invoiceSchema.nullable(),\n  creditNote: creditNoteSchema.nullable(),\n  refundedAt: z.iso.datetime().nullable(),\n});\nexport type PaymentDetail = z.infer<typeof paymentDetailSchema>;\n\n// ─── Staff: payments and refunds ─────────────────────────────────────────────\n\n/** Who paid, as they are now, so staff can find them. Email only for a role that may read it. */\nexport const payerSchema = z.object({\n  id: objectIdSchema,\n  displayName: z.string(),\n  email: z.string().nullable(),\n});\nexport type Payer = z.infer<typeof payerSchema>;\n\nexport const staffPaymentsQuerySchema = paginationQuerySchema.extend({\n  status: orderStatusSchema.optional(),\n  memberId: objectIdSchema.optional(),\n  /** Only the ones a person must act on (`needsAction` below). */\n  needsAction: z.preprocess(emptyStringToUndefined, z.stringbool().default(false)),\n});\nexport type StaffPaymentsQuery = z.infer<typeof staffPaymentsQuerySchema>;\nexport type StaffPaymentsQueryInput = z.input<typeof staffPaymentsQuerySchema>;\n\nexport const staffPaymentSummarySchema = paymentSummarySchema.extend({\n  payer: payerSchema,\n  /**\n   * A person must act (0.12.0): taken but not applied and not yet refunded\n   * (the automatic refund did not go through), a refund that failed at the\n   * gateway, or an open chargeback.\n   */\n  needsAction: z.boolean(),\n});\nexport type StaffPaymentSummary = z.infer<typeof staffPaymentSummarySchema>;\nexport const staffPaymentPageSchema = paginatedSchema(staffPaymentSummarySchema);\nexport type StaffPaymentPage = z.infer<typeof staffPaymentPageSchema>;\n\nexport const staffPaymentDetailSchema = paymentDetailSchema.extend({\n  payer: payerSchema,\n  razorpay: z.object({\n    orderId: z.string().nullable(),\n    paymentId: z.string().nullable(),\n    refundId: z.string().nullable(),\n  }),\n  /** Why staff refunded it, on record. */\n  refundReason: z.string().nullable(),\n  /**\n   * The money was taken but what it bought could not be applied when it was\n   * captured (they were a member already, the Premium time to upgrade had\n   * run out, past the 3-year cap): refund it. Null when it applied.\n   */\n  grantFailed: z.string().nullable(),\n  /** A chargeback was opened on it (cleared when it is won or closed). */\n  disputedAt: z.iso.datetime().nullable(),\n  /**\n   * What refunds made outside Founder Circle (the Razorpay dashboard) have\n   * already given back of this payment. A Refund here gives back the rest:\n   * `total` less this. 0 when there were none.\n   */\n  refundedOutside: paiseSchema,\n  /**\n   * Payments captured on this order other than the one that settled it (a\n   * late authorisation, a second Checkout attempt): each is refunded by\n   * itself; `refunded: false` means that refund has not gone through yet and\n   * the payment needs a person.\n   */\n  strayPayments: z.array(\n    z.object({\n      paymentId: z.string(),\n      amount: paiseSchema,\n      refunded: z.boolean(),\n      at: z.iso.datetime(),\n    }),\n  ),\n  viewer: z.object({\n    /** Paid, within the window, not their own, and the asker may refund. */\n    canRefund: z.boolean(),\n  }),\n});\nexport type StaffPaymentDetail = z.infer<typeof staffPaymentDetailSchema>;\n\nconst reasonSchema = z.string().trim().min(BILLING_REASON_MIN).max(BILLING_REASON_MAX);\n\n/** `POST /staff/payments/:orderId/refund`. The reason is on the audit record. */\nexport const refundPaymentBodySchema = z.object({ reason: reasonSchema });\nexport type RefundPaymentBody = z.infer<typeof refundPaymentBodySchema>;\n\n/**\n * `PUT /members/:memberId/membership`: grant (a partner, a press account) or\n * revoke (a fake or duplicate account holding a founding place). A paid one\n * is never revoked: refund its payment.\n */\nexport const setMembershipBodySchema = z.object({\n  granted: z.boolean(),\n  reason: reasonSchema,\n});\nexport type SetMembershipBody = z.infer<typeof setMembershipBodySchema>;\n\n// ─── Staff: coupons ──────────────────────────────────────────────────────────\n\n/** What a coupon is good for. A percent coupon names what it applies to. */\nexport const COUPON_TARGET_VALUES = ['membership', 'premium', 'business'] as const;\nexport const couponTargetSchema = z.enum(COUPON_TARGET_VALUES);\nexport type CouponTarget = z.infer<typeof couponTargetSchema>;\n\n/**\n * ⚠ Stored: append only.\n *\n *   free_membership  the membership at Rs 0; `founding` numbers its holders\n *                    (\"Founding member #N\")\n *   percent_off      a share off the listed price of what it applies to\n */\nexport const couponBenefitSchema = z.discriminatedUnion('kind', [\n  z.object({ kind: z.literal('free_membership'), founding: z.boolean() }),\n  z.object({\n    kind: z.literal('percent_off'),\n    percent: z.number().int().min(1).max(90),\n    appliesTo: z\n      .array(couponTargetSchema)\n      .min(1)\n      .max(COUPON_TARGET_VALUES.length)\n      .refine((list) => new Set(list).size === list.length, {\n        error: VALIDATION_MESSAGE.couponTargetsDuplicate,\n      }),\n  }),\n]);\nexport type CouponBenefit = z.infer<typeof couponBenefitSchema>;\n\nexport const couponSchema = z.object({\n  id: objectIdSchema,\n  code: z.string(),\n  label: z.string(),\n  benefit: couponBenefitSchema,\n  /** Redemptions allowed in all; null is no cap. */\n  max: z.number().int().positive().nullable(),\n  /** Redemptions in force (a revoked founding place frees one). */\n  used: z.number().int().nonnegative(),\n  active: z.boolean(),\n  validFrom: z.iso.datetime().nullable(),\n  validUntil: z.iso.datetime().nullable(),\n  createdAt: z.iso.datetime(),\n});\nexport type Coupon = z.infer<typeof couponSchema>;\n\n/** Never paged: coupons are few. Newest first. */\nexport const couponListSchema = z.object({ items: z.array(couponSchema) });\nexport type CouponList = z.infer<typeof couponListSchema>;\n\nexport const couponParamsSchema = z.object({ couponId: objectIdSchema });\nexport type CouponParams = z.infer<typeof couponParamsSchema>;\n\nconst windowValid = (body: { validFrom?: string | null; validUntil?: string | null }) =>\n  !body.validFrom || !body.validUntil || Date.parse(body.validFrom) < Date.parse(body.validUntil);\n\nexport const createCouponBodySchema = z\n  .object({\n    code: couponCodeSchema,\n    label: z.string().trim().min(2).max(COUPON_LABEL_MAX),\n    benefit: couponBenefitSchema,\n    max: z.number().int().positive().nullable(),\n    validFrom: z.iso.datetime().nullable().optional(),\n    validUntil: z.iso.datetime().nullable().optional(),\n  })\n  .refine(windowValid, { path: ['validUntil'], error: VALIDATION_MESSAGE.couponWindowInvalid });\nexport type CreateCouponBody = z.infer<typeof createCouponBodySchema>;\n\n/**\n * What may change on a live coupon. The code and the benefit never change: a\n * redemption is a record of what a code gave when it was used.\n */\nexport const updateCouponBodySchema = z\n  .object({\n    label: z.string().trim().min(2).max(COUPON_LABEL_MAX).optional(),\n    active: z.boolean().optional(),\n    max: z.number().int().positive().nullable().optional(),\n    validFrom: z.iso.datetime().nullable().optional(),\n    validUntil: z.iso.datetime().nullable().optional(),\n  })\n  .refine(windowValid, { path: ['validUntil'], error: VALIDATION_MESSAGE.couponWindowInvalid });\nexport type UpdateCouponBody = z.infer<typeof updateCouponBodySchema>;\n"]}