@happyvertical/accounting 0.91.0 → 0.94.0

package/README.md

@@ -37,11 +37,170 @@ complete billing address before creating the invoice so Stripe can calculate
 tax from that customer tax location. Read the invoice back to persist Stripe's
 calculated `taxAmount`; callers do not supply local tax tables or rates.
 
+Invoice lines carry more than an amount:
+
+- `periodStart` / `periodEnd` (set both) become the Stripe invoice item's
+  service `period`, so the invoice PDF, portal, and revenue reports show the
+  billed window. `periodEnd` is exclusive, like Stripe's own subscription
+  periods, and must not be before `periodStart`.
+- `discount` is the line's total discount in major units. Stripe receives it
+  as an amount-off coupon on the invoice item (one reusable coupon per
+  currency and amount, id `hv_amount_off_<currency>_<stripe amount>`), so the
+  discount shows on the invoice and Stripe Tax taxes the discounted amount.
+
+`collectionMethod: 'charge_automatically'` bills the customer's default
+payment method instead of emailing a payable invoice (the default,
+`send_invoice`). `invoices.send()` then finalizes the invoice with automatic
+collection on: Stripe charges the card on its own collection schedule (not
+necessarily at once, so activate service on `invoice.paid` rather than on
+`send()`), retries failures under your Stripe retry settings, and reports the
+result as `invoice.paid` or `invoice.payment_failed`. Automatically charged invoices carry no due date.
+`invoices.markUncollectible()` writes an open invoice off, and invoice reads
+report that state as `status: 'uncollectible'`.
+
+`invoices.markPaidOutOfBand()` closes an invoice that was paid on another
+rail (for example a crypto payment for a Stripe-issued invoice): Stripe marks
+it `paid_out_of_band`, which stops its emails, dunning, and automatic charges.
+It is idempotent (an invoice already closed out of band, or paid with
+nothing collected — a zero total or a credit balance — is left alone), throws
+for an invoice Stripe collected money for itself (a second collection needs a
+refund, not a silent close), finalizes a draft first without automatic
+collection and refuses it if finalization raised the amount due, pays an
+uncollectible invoice, and refuses a void one. Invoice reads report `paidOutOfBand`, so a consumer can tell such
+an invoice from one Stripe collected.
+
+## Stripe customers
+
+Pass a stable `idempotencyKey` when a retry might create the customer again
+(for example a worker that crashed before storing the returned id). A retry
+with the same key returns the first customer: Stripe replays the create
+inside its idempotency window, and after it the adapter finds the customer by
+the `local_id` metadata it writes on every customer (the oldest one wins if
+earlier retries left duplicates). Reuse the key only for the same customer
+contents.
+
+```ts
+const { externalId } = await stripe.customers.sync({
+  id: account.id,
+  name: account.name,
+  billingAddress: account.address,
+  idempotencyKey: `billing-account:${account.id}`,
+});
+```
+
 ## Stripe Checkout and webhooks
 
 `billing.createCheckoutSession` accepts `idempotencyKey`; reuse it when
-retrying the same Checkout Session creation. After `webhooks.verify` succeeds,
-the parsed Stripe webhook exposes its provider event as `WebhookEvent.id`.
+retrying the same Checkout Session creation.
+
+Price ad-hoc Checkout lines with `priceData.unitAmountMinor`, integer ISO 4217
+minor units that the adapter converts to Stripe's unit (ISK and UGX are
+two-decimal at Stripe). `priceData.unitAmount` is still accepted and passed
+through unconverted in Stripe's unit. Set `automaticTax: true` to charge tax
+with Stripe Tax; Stripe needs the buyer's location, so collect it with
+`billingAddressCollection` or, for an existing customer, save it with
+`customerUpdate: { address: 'auto' }`. Ad-hoc prices default to
+`taxBehavior: 'exclusive'` when tax is on.
+
+```ts
+const session = await stripe.billing.createCheckoutSession({
+  mode: 'payment',
+  customerExternalId: 'cus_123',
+  lineItems: [
+    {
+      priceData: { currency: 'CAD', unitAmountMinor: 5000, productName: 'Credit' },
+    },
+  ],
+  automaticTax: true,
+  customerUpdate: { address: 'auto' },
+  setupFutureUsage: 'off_session', // also keep the card for top-ups
+  successUrl,
+  cancelUrl,
+  idempotencyKey: `credit-purchase:${cartId}`,
+});
+```
+
+### Card on file
+
+A `setup` mode session saves a payment method without charging. It takes no
+line items and needs `currency` (or `paymentMethodTypes`). After it completes,
+read the saved method and make it the customer's default so automatically
+charged invoices and off-session charges can use it:
+
+```ts
+const setup = await stripe.billing.createCheckoutSession({
+  mode: 'setup',
+  customerExternalId: 'cus_123',
+  currency: 'CAD',
+  billingAddressCollection: 'required',
+  customerUpdate: { address: 'auto', name: 'auto' },
+  successUrl,
+  cancelUrl,
+  idempotencyKey: `card-setup:${accountId}:${attempt}`,
+});
+// On checkout.session.completed:
+// Both methods are optional on StripeBillingOperations; StripeProvider has them.
+const done = await stripe.billing.retrieveCheckoutSession?.(setup.externalId);
+if (done?.status === 'complete' && done.paymentMethodExternalId) {
+  await stripe.billing.setDefaultPaymentMethod?.(
+    'cus_123',
+    done.paymentMethodExternalId,
+  );
+}
+```
+
+## Off-session charges
+
+`payments.chargeSavedPaymentMethod()` charges a saved payment method without
+the customer present, for example an automatic prepaid-credit top-up. It is
+provider-neutral and optional on `PaymentOperations`: a provider that cannot
+pull funds from a stored method (such as a push-payment BTC rail) does not
+implement it, so check for it before calling. Amounts are integer minor units
+(`amountMinor`), and `idempotencyKey` is required.
+
+```ts
+const charge = await stripe.payments.chargeSavedPaymentMethod?.({
+  customerExternalId: 'cus_123', // default payment method unless one is given
+  amountMinor: 2500,
+  currency: 'USD',
+  idempotencyKey: `topup:${policyId}:${sequence}`,
+  metadata: { policy: policyId },
+});
+switch (charge?.status) {
+  case 'succeeded': // funds secured: grant the credit
+  case 'processing': // wait for the payment webhook
+  case 'requires_action': // issuer wants authentication; re-save the card on-session
+  case 'failed': // declined or no payment method; see failureCode
+}
+```
+
+A decline (`failureCode: 'card_declined'`) or an authentication requirement
+(`requires_action`, `failureCode: 'authentication_required'`) is returned, not
+thrown. Results never include Stripe's client secret, so a `requires_action`
+attempt is not completed later: when the customer is next present, collect
+authentication with a `setup` mode Checkout session and
+`setDefaultPaymentMethod`, then charge again with a new idempotency key (the
+old key returns the original, unauthenticated attempt). Other Stripe API
+errors throw a `StripeApiError` carrying `status`, `type`, and `code`;
+invalid input and a reused-key refusal throw a plain `Error` before any
+provider request. Every retry with the same key returns the original
+charge: Stripe replays it inside its idempotency window, and after it the
+adapter finds the PaymentIntent by its `hv_charge_key` metadata. Scope keys
+to the payer and use a new key for a new attempt: a key reused for a
+different amount, currency, customer, or explicit payment method is refused
+(Stripe `idempotency_error`, or an adapter error after the window), never
+charged. Pass `paymentMethodExternalId` to keep retries identical when the
+customer's default card may change in between. Payment webhooks (`payment_intent.*`) carry a normalized `WebhookEvent.payment`
+summary with the status, minor-unit amount, and `chargeKey`.
+
+Minor-unit amounts (`amountMinor`, `unitAmountMinor`, and the `*Minor` read
+fields) use ISO 4217 exponents from an explicit table, not the runtime's
+`Intl` display digits, which differ for some currencies (for example RSD,
+IQD, and MGA). Derive minor units the same way before calling.
+
+## Stripe webhooks
+
+After `webhooks.verify` succeeds, the parsed Stripe webhook exposes its provider event as `WebhookEvent.id`.
 Persist that identifier in a durable inbox before applying side effects; the
 in-process parser alone cannot deduplicate deliveries across restarts or
 replicas.

package/dist/chunks/{OAuthClient-Bv-lzpx8.js → OAuthClient-DgRaQp_Y.js}

@@ -1,4 +1,4 @@
-import { a as __toCommonJS, i as __require, n as __esmMin, r as __exportAll, t as __commonJSMin } from "./quickbooks-BF3GrJBw.js";
+import { a as __toCommonJS, i as __require, n as __esmMin, r as __exportAll, t as __commonJSMin } from "./quickbooks-DujZt_Gx.js";
 //#region ../../node_modules/.pnpm/atob@2.1.2/node_modules/atob/browser-atob.js
 var require_browser_atob = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function(w) {
@@ -18261,4 +18261,4 @@ var require_OAuthClient = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#endregion
 export default require_OAuthClient();
 
-//# sourceMappingURL=OAuthClient-Bv-lzpx8.js.map
+//# sourceMappingURL=OAuthClient-DgRaQp_Y.js.map