@devly-cl/billing-fintoc 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @devly-cl/billing-fintoc
+
+Fintoc billing adapter for Node 24+. Depends only on `@devly-cl/billing-core`; CommonJS, ESM consumers and NodeNext declarations share the same provider and core error constructors. Published releases are installed from npm; local `npm pack` only creates a candidate tarball.
+
+## Install
+
+```sh
+npm install @devly-cl/billing-core @devly-cl/billing-fintoc
+```
+
+## Public API
+
+The runtime entry exports `FintocBillingProvider`. Type exports are `FintocBillingProviderOptions`, `FintocRequestContext` and `FintocTransport`. Import operation inputs, results, capabilities and `SubscriptionGatewayError` from `@devly-cl/billing-core`. The HTTP client, subscription mapper and parsers are internal; deep imports are blocked.
+
+Construct the provider with a fixed `environment` (`test` or `live`) and getters `getSecretKey()`, `getWebhookSecret()` and `getReturnUrl(kind)` (`success` or `cancel`). Construction does not validate credentials or contact Fintoc. Getters run when the operation requires them; credential rotation never changes the instance's environment. Binding and capability values are frozen.
+
+Optional `transport(url, init)` replaces native fetch and `now()` supplies milliseconds since epoch for webhook expiry. The declaration includes fetch platform types explicitly and does not require Nest, TypeORM or implicit Node type dependencies in consumers.
+
+The host implements `beforeRequest({ method, path, collection })` for sales policy. New mutations have `collection: true`; GET and subscription cancellation have `collection: false`. Throw a safe core error to block an operation before dispatch. Environment-specific approval checks can live in the secret getter. Selection, legacy fallback, secret storage and authorization remain host responsibilities.
+
+`assertReady()` and `assertReady('subscriptionCheckout')` preserve credential-only readiness. `assertReady('paymentMethodSetup')` additionally checks collection policy and both return URLs. Checkout and setup operations always validate their actual return URLs. General availability therefore does not promise that a hosted setup can start.
+
+## Behavior
+
+Subscription checkout, canonical subscription/invoice reads, cancellation, recurring terms, one-off draft/finalize invoices and payment-method setup/change implement the core provider port. Mutations carry `Idempotency-Key`; wire calls use `/v2`, `Fintoc-Version: 2026-02-01`, a 15-second timeout, JSON and redirect rejection. Each call makes one attempt. Transport/JSON failures and mutation HTTP 408/409/429/5xx remain uncertain; successful mutation responses with invalid canonical evidence are also uncertain. No response body, URL or transport cause is attached to errors.
+
+`verifyEvent(rawBody, signature)` verifies the original bytes, HMAC, timestamp within 300 seconds, multiple rotation signatures and pinned mode. Webhooks are capped at 1 MiB; invoice pages at 50 entries. Verification returns a canonical event hint, not payment confirmation. Durable inboxes, retries, tenant ownership, database transactions, RBAC and audit stay in the host; the package does not persist state or retry automatically.
+
+## Integration example
+
+The host supplies credentials and policy; the declarations below are integration requirements, not working credentials. Constructing the adapter and checking readiness make no provider request.
+
+```ts
+import { SubscriptionGatewayError } from '@devly-cl/billing-core';
+import { FintocBillingProvider } from '@devly-cl/billing-fintoc';
+
+declare const host: {
+  testSecretKey(): string;
+  testWebhookSecret(): string;
+  returnUrl(kind: 'success' | 'cancel'): string;
+  collectionEnabled(): boolean;
+};
+
+const provider = new FintocBillingProvider({
+  environment: 'test',
+  getSecretKey: () => host.testSecretKey(),
+  getWebhookSecret: () => host.testWebhookSecret(),
+  getReturnUrl: (kind) => host.returnUrl(kind),
+  beforeRequest: ({ collection }) => {
+    if (collection && !host.collectionEnabled()) {
+      throw new SubscriptionGatewayError('BILLING_PROVIDER_DISABLED');
+    }
+  },
+});
+provider.assertReady('paymentMethodSetup');
+```
+
+Use a separate instance and credential getters for live. Implement environment approval in those getters when required by the host. Keep maintenance reads/cancellation and new collection policy distinct; retain stricter existing live gates when migrating an application. For webhooks, pass the original bytes to `verifyEvent` and durably enqueue the verified event before acknowledging HTTP; later reconciliation must establish canonical invoice evidence.
+
+## Validation
+
+Build from this repository root with `npm run build:packages`. Run `npm run test:packages`, `npm run test:package-boundaries` and `npm run test:package-artifacts`. The artifact consumer installs only Fintoc and core tarballs offline, verifies a synthetic operation/signature and CJS/ESM/NodeNext compatibility. These checks do not demonstrate a real PSP transaction or production credential readiness.
+
+During development, run `npm run build:packages` after changing package sources, then restart Nest. `start:dev` builds packages once at startup; automatic package hot reload has not been validated.

package/dist/fintoc-billing.provider.d.ts

@@ -0,0 +1,38 @@
+import type { FintocBillingProviderOptions } from './fintoc-provider.options';
+import type { SubscriptionCheckoutInput } from '@devly-cl/billing-core';
+import type { BillingProviderCapability, BillingProviderPort, ChangeRecurringTermsInput, CreateOneOffInvoiceInput, CreatePaymentMethodSetupInput, FinalizeOneOffInvoiceInput, ProviderBinding, ProviderOneOffInvoice, ProviderPaymentMethodSetup, ProviderRecurringTerms, SetSubscriptionPaymentMethodInput, VerifiedBillingEvent } from '@devly-cl/billing-core';
+/** Fintoc API 2026-02-01. Each instance is permanently bound to one environment. */
+export declare class FintocBillingProvider implements BillingProviderPort {
+    readonly webhookSignatureHeader = "fintoc-signature";
+    readonly binding: ProviderBinding;
+    readonly capabilities: readonly BillingProviderCapability[];
+    private readonly transport;
+    private readonly subscriptions;
+    constructor(options: FintocBillingProviderOptions);
+    assertReady(capability?: BillingProviderCapability): void;
+    createCheckout(input: SubscriptionCheckoutInput): Promise<import("@devly-cl/billing-core").SubscriptionCheckout>;
+    getCheckout(id: string): Promise<import("@devly-cl/billing-core").SubscriptionCheckout>;
+    getSubscription(id: string): Promise<import("@devly-cl/billing-core").ProviderSubscription>;
+    cancelSubscription(id: string, key: string): Promise<import("@devly-cl/billing-core").ProviderSubscription>;
+    getInvoice(id: string): Promise<import("@devly-cl/billing-core").ProviderInvoice>;
+    listInvoices(id: string, cursor?: string): Promise<{
+        items: import("@devly-cl/billing-core").ProviderInvoice[];
+        nextCursor: string | null;
+    }>;
+    verifyEvent(rawBody: Uint8Array, signature: string | undefined): VerifiedBillingEvent;
+    getRecurringTerms(subscriptionId: string): Promise<ProviderRecurringTerms>;
+    changeRecurringTerms(input: ChangeRecurringTermsInput): Promise<ProviderRecurringTerms>;
+    createOneOffInvoice(input: CreateOneOffInvoiceInput): Promise<ProviderOneOffInvoice>;
+    getOneOffInvoice(invoiceId: string): Promise<ProviderOneOffInvoice>;
+    finalizeOneOffInvoice(input: FinalizeOneOffInvoiceInput): Promise<ProviderOneOffInvoice>;
+    createPaymentMethodSetup(input: CreatePaymentMethodSetupInput): Promise<ProviderPaymentMethodSetup>;
+    getPaymentMethodSetup(setupId: string): Promise<ProviderPaymentMethodSetup>;
+    setSubscriptionPaymentMethod(input: SetSubscriptionPaymentMethodInput): Promise<ProviderRecurringTerms>;
+    private recurringItem;
+    private assertSubscriptionOwner;
+    private assertPaymentMethod;
+    private oneOffInvoice;
+    private assertInvoice;
+    private paymentMethodSetup;
+    private confirmSetup;
+}

package/dist/fintoc-billing.provider.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FintocBillingProvider = void 0;
+const billing_core_1 = require("@devly-cl/billing-core");
+const fintoc_subscription_gateway_1 = require("./fintoc-subscription.gateway");
+const fintoc_http_client_1 = require("./fintoc-http.client");
+const validAmount = (amount, currency) => {
+    if (!Number.isSafeInteger(amount) || amount < 1 || currency !== 'CLP')
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_TERMS_INVALID');
+};
+const validLabel = (value) => {
+    if (typeof value !== 'string' ||
+        !value.trim() ||
+        value.length > 200 ||
+        Array.from(value).some((character) => character.charCodeAt(0) < 32))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_TERMS_INVALID');
+    return value;
+};
+const operationId = (value) => {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9:._-]{1,128}$/.test(value))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_OPERATION_ID_INVALID');
+    return value;
+};
+const utcDate = (value) => {
+    if (typeof value !== 'string' ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/.test(value) ||
+        !Number.isFinite(Date.parse(value)))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PERIOD_INVALID');
+    const result = new Date(value).toISOString();
+    if (result.slice(0, 19) !== value.slice(0, 19))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PERIOD_INVALID');
+    return result;
+};
+const period = (start, end) => {
+    const result = { start: utcDate(start), end: utcDate(end) };
+    if (result.start >= result.end)
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PERIOD_INVALID');
+    return result;
+};
+/** Fintoc API 2026-02-01. Each instance is permanently bound to one environment. */
+class FintocBillingProvider {
+    webhookSignatureHeader = 'fintoc-signature';
+    binding;
+    capabilities = Object.freeze([
+        'subscriptionCheckout',
+        'recurringPriceChange',
+        'recurringIntervalChange',
+        'oneOffInvoice',
+        'paymentMethodSetup',
+        'paymentMethodChange',
+        'webhookVerification',
+    ]);
+    transport;
+    subscriptions;
+    constructor(options) {
+        const environment = options.environment;
+        if (!['test', 'live'].includes(environment))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_BINDING_INVALID');
+        this.binding = Object.freeze({ provider: 'fintoc', environment });
+        this.transport = new fintoc_http_client_1.FintocHttpClient(options, environment);
+        this.subscriptions = new fintoc_subscription_gateway_1.FintocSubscriptionGateway(this.transport);
+    }
+    assertReady(capability) {
+        if (capability === 'paymentMethodSetup') {
+            this.transport.assertCollectionReady();
+            this.transport.returnUrl('success');
+            this.transport.returnUrl('cancel');
+        }
+        else
+            this.transport.credentials();
+    }
+    createCheckout(input) {
+        return this.subscriptions.createCheckout(input);
+    }
+    getCheckout(id) {
+        return this.subscriptions.getCheckout(id);
+    }
+    getSubscription(id) {
+        return this.subscriptions.getSubscription(id);
+    }
+    cancelSubscription(id, key) {
+        return this.subscriptions.cancelSubscription(id, key);
+    }
+    getInvoice(id) {
+        return this.subscriptions.getInvoice(id);
+    }
+    listInvoices(id, cursor) {
+        return this.subscriptions.listInvoices(id, cursor);
+    }
+    verifyEvent(rawBody, signature) {
+        if (!(rawBody instanceof Uint8Array) || rawBody.byteLength > 1_048_576)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        return this.subscriptions.verifyWebhook(Buffer.from(rawBody), signature);
+    }
+    async getRecurringTerms(subscriptionId) {
+        const id = (0, fintoc_http_client_1.fintocIdentifier)(subscriptionId, 'sub');
+        const data = (0, fintoc_http_client_1.fintocObject)(await this.transport.request(`/subscriptions/${id}`));
+        if ((0, fintoc_http_client_1.fintocIdentifier)(data.id, 'sub') !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_MISMATCH');
+        if (!Array.isArray(data.items) || data.items.length !== 1)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_UNSUPPORTED');
+        const item = this.recurringItem(data.items[0]);
+        const status = (0, fintoc_http_client_1.fintocString)(data.status);
+        if (!['active', 'incomplete', 'trialing', 'canceled'].includes(status))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_UNSUPPORTED');
+        return {
+            id,
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            mode: this.transport.mode(data.mode),
+            status,
+            ...item,
+            paymentMethodId: data.payment_method === null
+                ? null
+                : (0, fintoc_http_client_1.fintocIdentifier)(data.payment_method, 'pm'),
+            billingCycleAnchor: utcDate(data.billing_cycle_anchor),
+            periodStart: null,
+            periodEnd: null,
+            nextInvoiceAt: null,
+        };
+    }
+    async changeRecurringTerms(input) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(input.idempotencyKey);
+        validAmount(input.amount, input.currency);
+        validAmount(input.expectedCurrent.amount, input.currency);
+        validLabel(input.label);
+        if (!['month', 'year'].includes(input.interval) ||
+            !['month', 'year'].includes(input.expectedCurrent.interval))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_TERMS_INVALID');
+        (0, fintoc_http_client_1.fintocIdentifier)(input.itemId, 'si');
+        (0, fintoc_http_client_1.fintocIdentifier)(input.customerId, 'cus');
+        const current = await this.getRecurringTerms(input.subscriptionId);
+        this.assertSubscriptionOwner(current, input.customerId);
+        if (input.expectedBillingCycleAnchor &&
+            current.billingCycleAnchor !== utcDate(input.expectedBillingCycleAnchor))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_BILLING_ANCHOR_MISMATCH');
+        if (current.itemId !== input.itemId)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_MISMATCH');
+        if (current.amount === input.amount && current.interval === input.interval)
+            return current;
+        if (current.amount !== input.expectedCurrent.amount ||
+            current.interval !== input.expectedCurrent.interval)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_TERMS_CHANGED');
+        return this.transport.mutation(() => this.transport.request(`/subscriptions/${current.id}/items/${current.itemId}`, 'PATCH', {
+            price_data: {
+                currency: input.currency,
+                unit_amount: input.amount,
+                product_data: { name: input.label },
+                recurring: { interval: input.interval, interval_count: 1 },
+            },
+            quantity: 1,
+        }, input.idempotencyKey), async (raw) => {
+            const item = this.recurringItem(raw);
+            if (item.itemId !== current.itemId ||
+                item.amount !== input.amount ||
+                item.interval !== input.interval)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_TERMS_MISMATCH');
+            const updated = await this.getRecurringTerms(current.id);
+            this.assertSubscriptionOwner(updated, input.customerId);
+            if (updated.billingCycleAnchor !== current.billingCycleAnchor)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_BILLING_ANCHOR_MISMATCH');
+            if (updated.itemId !== current.itemId ||
+                updated.amount !== input.amount ||
+                updated.interval !== input.interval)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_TERMS_MISMATCH');
+            return updated;
+        });
+    }
+    async createOneOffInvoice(input) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(input.idempotencyKey);
+        validAmount(input.amount, input.currency);
+        validLabel(input.label);
+        operationId(input.localOperationId);
+        const servicePeriod = period(input.periodStart, input.periodEnd);
+        await this.assertPaymentMethod(input.paymentMethodId, input.customerId);
+        return this.transport.mutation(() => this.transport.request('/invoices', 'POST', {
+            customer: input.customerId,
+            default_payment_method: input.paymentMethodId,
+            collection_method: 'charge_automatically',
+            lines: [
+                {
+                    name: input.label,
+                    amount: input.amount,
+                    currency: input.currency,
+                    quantity: 1,
+                },
+            ],
+            metadata: {
+                operation_external_id: input.localOperationId,
+                service_period_start: servicePeriod.start,
+                service_period_end: servicePeriod.end,
+            },
+        }, input.idempotencyKey), (raw) => {
+            const invoice = this.oneOffInvoice(raw);
+            this.assertInvoice(invoice, input);
+            return invoice;
+        });
+    }
+    async getOneOffInvoice(invoiceId) {
+        const id = (0, fintoc_http_client_1.fintocIdentifier)(invoiceId, 'inv');
+        const invoice = this.oneOffInvoice(await this.transport.request(`/invoices/${id}`));
+        if (invoice.id !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+        return invoice;
+    }
+    async finalizeOneOffInvoice(input) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(input.idempotencyKey);
+        validAmount(input.amount, input.currency);
+        (0, fintoc_http_client_1.fintocIdentifier)(input.customerId, 'cus');
+        (0, fintoc_http_client_1.fintocIdentifier)(input.paymentMethodId, 'pm');
+        operationId(input.localOperationId);
+        period(input.periodStart, input.periodEnd);
+        const current = await this.getOneOffInvoice(input.invoiceId);
+        this.assertInvoice(current, input);
+        if (current.status === 'open' || current.status === 'paid')
+            return current;
+        if (current.status !== 'draft')
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_NOT_PAYABLE');
+        return this.transport.mutation(() => this.transport.request(`/invoices/${current.id}/finalize`, 'POST', {}, input.idempotencyKey), (raw) => {
+            const invoice = this.oneOffInvoice(raw);
+            this.assertInvoice(invoice, input);
+            if (invoice.id !== current.id ||
+                !['open', 'paid'].includes(invoice.status))
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+            return invoice;
+        });
+    }
+    async createPaymentMethodSetup(input) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(input.idempotencyKey);
+        operationId(input.localOperationId);
+        (0, fintoc_http_client_1.fintocIdentifier)(input.customerId, 'cus');
+        const successUrl = this.transport.returnUrl('success');
+        const cancelUrl = this.transport.returnUrl('cancel');
+        const subscription = await this.getRecurringTerms(input.subscriptionId);
+        this.assertSubscriptionOwner(subscription, input.customerId);
+        return this.transport.mutation(() => this.transport.request('/checkout_sessions', 'POST', {
+            flow: 'setup',
+            subscription: subscription.id,
+            customer: input.customerId,
+            currency: 'CLP',
+            payment_method_types: ['pac', 'card'],
+            success_url: successUrl,
+            cancel_url: cancelUrl,
+            metadata: { operation_external_id: input.localOperationId },
+        }, input.idempotencyKey), async (raw) => {
+            const setup = this.paymentMethodSetup(raw);
+            if (setup.customerId !== input.customerId ||
+                setup.subscriptionId !== subscription.id ||
+                setup.localOperationId !== input.localOperationId)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+            if (setup.status === 'finished')
+                await this.confirmSetup(setup);
+            return setup;
+        });
+    }
+    async getPaymentMethodSetup(setupId) {
+        const id = (0, fintoc_http_client_1.fintocIdentifier)(setupId, 'cs');
+        const setup = this.paymentMethodSetup(await this.transport.request(`/checkout_sessions/${id}`));
+        if (setup.id !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+        if (setup.status === 'finished')
+            await this.confirmSetup(setup);
+        return setup;
+    }
+    async setSubscriptionPaymentMethod(input) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(input.idempotencyKey);
+        (0, fintoc_http_client_1.fintocIdentifier)(input.customerId, 'cus');
+        (0, fintoc_http_client_1.fintocIdentifier)(input.paymentMethodId, 'pm');
+        const current = await this.getRecurringTerms(input.subscriptionId);
+        this.assertSubscriptionOwner(current, input.customerId);
+        await this.assertPaymentMethod(input.paymentMethodId, input.customerId);
+        if (current.paymentMethodId === input.paymentMethodId)
+            return current;
+        return this.transport.mutation(() => this.transport.request(`/subscriptions/${current.id}`, 'PATCH', { payment_method: input.paymentMethodId }, input.idempotencyKey), async (value) => {
+            const raw = (0, fintoc_http_client_1.fintocObject)(value);
+            if ((0, fintoc_http_client_1.fintocIdentifier)(raw.id, 'sub') !== current.id ||
+                (0, fintoc_http_client_1.fintocIdentifier)(raw.customer, 'cus') !== input.customerId ||
+                (0, fintoc_http_client_1.fintocIdentifier)(raw.payment_method, 'pm') !== input.paymentMethodId)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PAYMENT_METHOD_MISMATCH');
+            this.transport.mode(raw.mode);
+            const updated = await this.getRecurringTerms(current.id);
+            this.assertSubscriptionOwner(updated, input.customerId);
+            if (updated.paymentMethodId !== input.paymentMethodId)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PAYMENT_METHOD_MISMATCH');
+            return updated;
+        });
+    }
+    recurringItem(value) {
+        const item = (0, fintoc_http_client_1.fintocObject)(value), price = (0, fintoc_http_client_1.fintocObject)(item.price), recurring = (0, fintoc_http_client_1.fintocObject)(price.recurring);
+        if ((0, fintoc_http_client_1.fintocInteger)(item.quantity) !== 1 ||
+            price.currency !== 'CLP' ||
+            (0, fintoc_http_client_1.fintocInteger)(recurring.interval_count) !== 1 ||
+            !['month', 'year'].includes(String(recurring.interval)))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_UNSUPPORTED');
+        const amount = (0, fintoc_http_client_1.fintocInteger)(price.unit_amount);
+        validAmount(amount, price.currency);
+        return {
+            itemId: (0, fintoc_http_client_1.fintocIdentifier)(item.id, 'si'),
+            amount,
+            currency: 'CLP',
+            interval: recurring.interval,
+            quantity: 1,
+        };
+    }
+    assertSubscriptionOwner(subscription, customerId) {
+        if (subscription.customerId !== customerId)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_CUSTOMER_MISMATCH');
+        if (subscription.status === 'canceled')
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_NOT_EDITABLE');
+    }
+    async assertPaymentMethod(paymentMethodId, customerId) {
+        const id = (0, fintoc_http_client_1.fintocIdentifier)(paymentMethodId, 'pm');
+        (0, fintoc_http_client_1.fintocIdentifier)(customerId, 'cus');
+        const method = (0, fintoc_http_client_1.fintocObject)(await this.transport.request(`/payment_methods/${id}`));
+        this.transport.mode(method.mode);
+        if ((0, fintoc_http_client_1.fintocIdentifier)(method.id, 'pm') !== id ||
+            (0, fintoc_http_client_1.fintocIdentifier)(method.customer, 'cus') !== customerId)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PAYMENT_METHOD_MISMATCH');
+        if (!((method.type === 'pac' && (0, fintoc_http_client_1.fintocObject)(method.pac).status === 'active') ||
+            (method.type === 'card' && (0, fintoc_http_client_1.fintocObject)(method.card).active === true)))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_PAYMENT_METHOD_UNAVAILABLE');
+    }
+    oneOffInvoice(value) {
+        const data = (0, fintoc_http_client_1.fintocObject)(value);
+        if (data.subscription !== null ||
+            data.collection_method !== 'charge_automatically' ||
+            !Array.isArray(data.lines) ||
+            data.lines.length !== 1 ||
+            !Array.isArray(data.payments) ||
+            !['draft', 'open', 'paid', 'void'].includes(String(data.status)))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_UNSUPPORTED');
+        const line = (0, fintoc_http_client_1.fintocObject)(data.lines[0]), metadata = (0, fintoc_http_client_1.fintocObject)(data.metadata);
+        const amount = (0, fintoc_http_client_1.fintocInteger)(data.total);
+        validAmount(amount, (0, fintoc_http_client_1.fintocString)(data.currency));
+        if ((0, fintoc_http_client_1.fintocInteger)(line.amount) !== amount ||
+            line.currency !== data.currency ||
+            (0, fintoc_http_client_1.fintocInteger)(line.quantity) !== 1 ||
+            line.period_start !== null ||
+            line.period_end !== null)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+        if (data.external_payment !== undefined &&
+            typeof data.external_payment !== 'boolean')
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID');
+        const servicePeriod = period(metadata.service_period_start, metadata.service_period_end);
+        const confirmed = data.status === 'paid' &&
+            data.external_payment === false &&
+            data.payments.some((value) => {
+                const payment = (0, fintoc_http_client_1.fintocObject)(value);
+                if (payment.status !== 'succeeded' ||
+                    payment.amount !== amount ||
+                    payment.currency !== data.currency)
+                    return false;
+                try {
+                    (0, fintoc_http_client_1.fintocIdentifier)(payment.payment_intent, 'pi');
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        return {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(data.id, 'inv'),
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            paymentMethodId: (0, fintoc_http_client_1.fintocIdentifier)(data.default_payment_method, 'pm'),
+            localOperationId: operationId(metadata.operation_external_id),
+            mode: this.transport.mode(data.mode),
+            status: data.status,
+            amount,
+            currency: 'CLP',
+            paymentConfirmed: confirmed,
+            externalPayment: typeof data.external_payment === 'boolean'
+                ? data.external_payment
+                : null,
+            attemptCount: (0, fintoc_http_client_1.fintocInteger)(data.attempt_count),
+            hostedUrl: this.transport.hostedUrl(data.hosted_invoice_url),
+            servicePeriodStart: servicePeriod.start,
+            servicePeriodEnd: servicePeriod.end,
+        };
+    }
+    assertInvoice(invoice, expected) {
+        const servicePeriod = period(expected.periodStart, expected.periodEnd);
+        if (invoice.customerId !== expected.customerId ||
+            invoice.paymentMethodId !== expected.paymentMethodId ||
+            invoice.localOperationId !== expected.localOperationId ||
+            invoice.amount !== expected.amount ||
+            invoice.currency !== expected.currency ||
+            invoice.servicePeriodStart !== servicePeriod.start ||
+            invoice.servicePeriodEnd !== servicePeriod.end)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+    }
+    paymentMethodSetup(value) {
+        const data = (0, fintoc_http_client_1.fintocObject)(value);
+        if (data.flow !== 'setup' ||
+            data.amount !== null ||
+            !['created', 'in_progress', 'finished', 'expired'].includes(String(data.status)))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+        const setup = {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(data.id, 'cs'),
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            subscriptionId: (0, fintoc_http_client_1.fintocIdentifier)(data.subscription, 'sub'),
+            localOperationId: operationId((0, fintoc_http_client_1.fintocObject)(data.metadata).operation_external_id),
+            mode: this.transport.mode(data.mode),
+            status: data.status,
+            paymentMethodId: data.payment_method === null
+                ? null
+                : (0, fintoc_http_client_1.fintocIdentifier)(data.payment_method, 'pm'),
+            redirectUrl: this.transport.hostedUrl(data.redirect_url),
+        };
+        if (['created', 'in_progress'].includes(setup.status) && !setup.redirectUrl)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+        return setup;
+    }
+    async confirmSetup(setup) {
+        if (!setup.paymentMethodId)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+        await this.assertPaymentMethod(setup.paymentMethodId, setup.customerId);
+        const subscription = await this.getRecurringTerms(setup.subscriptionId);
+        this.assertSubscriptionOwner(subscription, setup.customerId);
+        if (subscription.paymentMethodId !== setup.paymentMethodId)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SETUP_MISMATCH');
+    }
+}
+exports.FintocBillingProvider = FintocBillingProvider;

package/dist/fintoc-http.client.d.ts

@@ -0,0 +1,27 @@
+import type { FintocBillingProviderOptions } from './fintoc-provider.options';
+import type { BillingEnvironment } from '@devly-cl/billing-core';
+export type FintocJson = Record<string, unknown>;
+export declare const fintocObject: (value: unknown) => FintocJson;
+export declare const fintocString: (value: unknown) => string;
+export declare const fintocIdentifier: (value: unknown, prefix: string) => string;
+export declare const fintocInteger: (value: unknown) => number;
+export declare const billingIdempotencyKey: (key: string) => string;
+/** Shared native-fetch transport; performs one attempt, preserving uncertain mutations for reconciliation. */
+export declare class FintocHttpClient {
+    private readonly options;
+    private readonly environment;
+    constructor(options: FintocBillingProviderOptions, environment: BillingEnvironment);
+    credentials(): {
+        key: string;
+        mode: BillingEnvironment;
+    };
+    assertCollectionReady(): void;
+    webhookSecret(): string;
+    now(): number;
+    mode(value: unknown): BillingEnvironment;
+    hostedUrl(value: unknown): string | null;
+    returnUrl(kind: 'success' | 'cancel'): string;
+    request(path: string, method?: 'GET' | 'POST' | 'PATCH', body?: FintocJson, key?: string): Promise<unknown>;
+    private readJson;
+    mutation<T>(request: () => Promise<unknown>, reconcile: (raw: unknown) => Promise<T> | T): Promise<T>;
+}

package/dist/fintoc-http.client.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FintocHttpClient = exports.billingIdempotencyKey = exports.fintocInteger = exports.fintocIdentifier = exports.fintocString = exports.fintocObject = void 0;
+const billing_core_1 = require("@devly-cl/billing-core");
+const MAX_RESPONSE_BYTES = 1_048_576;
+const REQUEST_TIMEOUT_MS = 15_000;
+function withAbortDeadline(request, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', abort);
+            action();
+        };
+        const abort = () => settle(() => reject(new Error('Fintoc request deadline exceeded')));
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+        void request.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error instanceof Error
+            ? error
+            : new Error('Fintoc transport failed'))));
+    });
+}
+function discardResponseBody(response) {
+    if (response.body)
+        void response.body.cancel().catch(() => undefined);
+}
+const fintocObject = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID');
+    return value;
+};
+exports.fintocObject = fintocObject;
+const fintocString = (value) => {
+    if (typeof value !== 'string' || !value.trim())
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID');
+    return value;
+};
+exports.fintocString = fintocString;
+const fintocIdentifier = (value, prefix) => {
+    const id = typeof value === 'object' && value ? (0, exports.fintocObject)(value).id : value;
+    if (typeof id !== 'string' ||
+        !new RegExp(`^${prefix}_[A-Za-z0-9]+$`).test(id))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_ID_INVALID');
+    return id;
+};
+exports.fintocIdentifier = fintocIdentifier;
+const fintocInteger = (value) => {
+    if (!Number.isSafeInteger(value) || Number(value) < 0)
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID');
+    return Number(value);
+};
+exports.fintocInteger = fintocInteger;
+const billingIdempotencyKey = (key) => {
+    if (typeof key !== 'string' || !/^[\x21-\x7e]{1,255}$/.test(key))
+        throw new billing_core_1.SubscriptionGatewayError('BILLING_IDEMPOTENCY_KEY_REQUIRED');
+    return key;
+};
+exports.billingIdempotencyKey = billingIdempotencyKey;
+/** Shared native-fetch transport; performs one attempt, preserving uncertain mutations for reconciliation. */
+class FintocHttpClient {
+    options;
+    environment;
+    constructor(options, environment) {
+        this.options = options;
+        this.environment = environment;
+    }
+    credentials() {
+        const key = this.options.getSecretKey();
+        if (typeof key !== 'string' ||
+            !/^sk_(test|live)_[A-Za-z0-9_-]+$/.test(key) ||
+            !key.startsWith(`sk_${this.environment}_`))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_CONFIGURATION_REQUIRED');
+        return { key, mode: this.environment };
+    }
+    assertCollectionReady() {
+        this.options.beforeRequest?.({
+            method: 'POST',
+            path: '/checkout_sessions',
+            collection: true,
+        });
+        this.credentials();
+    }
+    webhookSecret() {
+        this.credentials();
+        const secret = this.options.getWebhookSecret();
+        if (typeof secret !== 'string' || !secret)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        return secret;
+    }
+    now() {
+        return this.options.now ? this.options.now() : Date.now();
+    }
+    mode(value) {
+        const expected = this.credentials().mode;
+        if (value !== expected)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_MODE_MISMATCH');
+        return expected;
+    }
+    hostedUrl(value) {
+        if (value === null || value === undefined)
+            return null;
+        let url;
+        try {
+            url = new URL((0, exports.fintocString)(value));
+        }
+        catch {
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_URL_INVALID');
+        }
+        if (url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            url.port ||
+            !(url.hostname === 'pay.fintoc.com' ||
+                url.hostname === 'checkout.fintoc.com' ||
+                /^[a-z0-9-]+\.billing\.fintoc\.com$/.test(url.hostname)))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_URL_INVALID');
+        return url.toString();
+    }
+    returnUrl(kind) {
+        let url;
+        try {
+            url = new URL((0, exports.fintocString)(this.options.getReturnUrl(kind)));
+        }
+        catch {
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_RETURN_URL_INVALID');
+        }
+        if (url.protocol !== 'https:' || url.username || url.password)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_RETURN_URL_INVALID');
+        return url.toString();
+    }
+    async request(path, method = 'GET', body, key) {
+        const mutation = method !== 'GET';
+        // Disabling new collections must not stop canonical reads, webhook checks,
+        // or an already authorized cancellation of renewal.
+        const cancellation = method === 'POST' &&
+            /^\/subscriptions\/sub_[A-Za-z0-9]+\/cancel$/.test(path);
+        this.options.beforeRequest?.({
+            method,
+            path,
+            collection: mutation && !cancellation,
+        });
+        const credentials = this.credentials();
+        if (mutation)
+            (0, exports.billingIdempotencyKey)(key ?? '');
+        const signal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            const url = `https://api.fintoc.com/v2${path}`;
+            const init = {
+                method,
+                redirect: 'error',
+                signal,
+                headers: {
+                    Authorization: credentials.key,
+                    'Fintoc-Version': '2026-02-01',
+                    'Content-Type': 'application/json',
+                    ...(key ? { 'Idempotency-Key': key } : {}),
+                },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+            };
+            const transport = this.options.transport;
+            response = await withAbortDeadline(transport === undefined || transport === null
+                ? globalThis.fetch(url, init)
+                : transport.call(this.options, url, init), signal);
+        }
+        catch {
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_UNCERTAIN', mutation);
+        }
+        // 408/409/429 and server failures cannot prove that a concurrent/in-flight mutation was not accepted.
+        if (!response.ok) {
+            discardResponseBody(response);
+            throw new billing_core_1.SubscriptionGatewayError(`BILLING_PROVIDER_HTTP_${response.status}`, mutation &&
+                (response.status >= 500 || [408, 409, 429].includes(response.status)));
+        }
+        try {
+            return await withAbortDeadline(this.readJson(response, signal), signal);
+        }
+        catch {
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID', mutation);
+        }
+    }
+    async readJson(response, signal) {
+        const declaredLength = response.headers.get('content-length');
+        if (declaredLength &&
+            (!/^\d+$/.test(declaredLength) ||
+                Number(declaredLength) > MAX_RESPONSE_BYTES)) {
+            discardResponseBody(response);
+            throw new Error('Response exceeds limit');
+        }
+        if (!response.body)
+            throw new Error('Empty response');
+        const reader = response.body.getReader();
+        const abort = () => {
+            void reader.cancel().catch(() => undefined);
+        };
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+        const chunks = [];
+        let length = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                length += value.byteLength;
+                if (length > MAX_RESPONSE_BYTES) {
+                    void reader.cancel().catch(() => undefined);
+                    throw new Error('Response exceeds limit');
+                }
+                chunks.push(Buffer.from(value));
+            }
+            return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, length)));
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            reader.releaseLock();
+        }
+    }
+    async mutation(request, reconcile) {
+        const raw = await request();
+        try {
+            return await reconcile(raw);
+        }
+        catch (error) {
+            if (error instanceof billing_core_1.SubscriptionGatewayError)
+                throw new billing_core_1.SubscriptionGatewayError(error.code, true);
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID', true);
+        }
+    }
+}
+exports.FintocHttpClient = FintocHttpClient;

package/dist/fintoc-provider.options.d.ts

@@ -0,0 +1,18 @@
+/// <reference lib="dom" preserve="true" />
+import type { BillingEnvironment } from '@devly-cl/billing-core';
+export type FintocTransport = (url: string, init: RequestInit) => Promise<Response>;
+export interface FintocRequestContext {
+    readonly method: 'GET' | 'POST' | 'PATCH';
+    readonly path: string;
+    readonly collection: boolean;
+}
+/** Dynamic host policy. Environment is fixed at construction; getters run only when needed. */
+export interface FintocBillingProviderOptions {
+    readonly environment: BillingEnvironment;
+    getSecretKey(): unknown;
+    getWebhookSecret(): unknown;
+    getReturnUrl(kind: 'success' | 'cancel'): unknown;
+    beforeRequest?(request: FintocRequestContext): void;
+    transport?: FintocTransport;
+    now?: () => number;
+}

package/dist/fintoc-provider.options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/fintoc-subscription.gateway.d.ts

@@ -0,0 +1,30 @@
+import { FintocHttpClient } from './fintoc-http.client';
+import { ProviderInvoice, ProviderSubscription, SubscriptionCheckout, SubscriptionCheckoutInput, SubscriptionGateway } from '@devly-cl/billing-core';
+/** Internal subscription operations; composed with the provider, never inherited. */
+export declare class FintocSubscriptionGateway implements SubscriptionGateway {
+    private readonly transport;
+    constructor(transport: FintocHttpClient);
+    createCheckout(input: SubscriptionCheckoutInput): Promise<SubscriptionCheckout>;
+    getCheckout(id: string): Promise<SubscriptionCheckout>;
+    getSubscription(id: string): Promise<ProviderSubscription>;
+    cancelSubscription(id: string, key: string): Promise<ProviderSubscription>;
+    getInvoice(id: string): Promise<ProviderInvoice>;
+    listInvoices(subscriptionId: string, cursor?: string): Promise<{
+        items: ProviderInvoice[];
+        nextCursor: string | null;
+    }>;
+    verifyWebhook(rawBody: Buffer, signature: string | undefined): {
+        id: string;
+        type: string;
+        resourceId: string;
+        mode: 'test' | 'live';
+    };
+    private checkout;
+    private subscription;
+    private invoice;
+    private hostedUrl;
+    private returnUrl;
+    private mode;
+    private credentials;
+    private request;
+}

package/dist/fintoc-subscription.gateway.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FintocSubscriptionGateway = void 0;
+const node_crypto_1 = require("node:crypto");
+const fintoc_http_client_1 = require("./fintoc-http.client");
+const billing_core_1 = require("@devly-cl/billing-core");
+/** Date.parse normalizes impossible calendar values, so validate RFC 3339 components first. */
+const strictIsoInstant = (value) => {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]), hour = Number(match[4]), minute = Number(match[5]), second = Number(match[6] ?? 0);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [
+        31,
+        leapYear ? 29 : 28,
+        31,
+        30,
+        31,
+        30,
+        31,
+        31,
+        30,
+        31,
+        30,
+        31,
+    ][month - 1];
+    if (year < 1 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > daysInMonth ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59)
+        return null;
+    if (match[7] !== 'Z') {
+        const [offsetHour, offsetMinute] = match[7].slice(1).split(':').map(Number);
+        if (offsetHour > 23 || offsetMinute > 59)
+            return null;
+    }
+    const instant = Date.parse(value);
+    return Number.isFinite(instant) ? instant : null;
+};
+/** Internal subscription operations; composed with the provider, never inherited. */
+class FintocSubscriptionGateway {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async createCheckout(input) {
+        if (!Number.isSafeInteger(input.amount) ||
+            input.amount < 1 ||
+            input.currency !== 'CLP' ||
+            !['month', 'year'].includes(input.interval))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_TERMS_INVALID');
+        const successUrl = this.returnUrl('success');
+        const cancelUrl = this.returnUrl('cancel');
+        return this.transport.mutation(() => this.request('/checkout_sessions', 'POST', {
+            flow: 'subscription',
+            currency: input.currency,
+            success_url: successUrl,
+            cancel_url: cancelUrl,
+            payment_method_types: ['pac', 'card'],
+            customer_data: {
+                name: input.customer.name,
+                email: input.customer.email,
+                tax_id: { type: 'cl_rut', value: input.customer.taxId },
+            },
+            line_items: [
+                {
+                    price_data: {
+                        currency: input.currency,
+                        unit_amount: input.amount,
+                        product_data: { name: input.label },
+                        recurring: { interval: input.interval, interval_count: 1 },
+                    },
+                    quantity: 1,
+                },
+            ],
+            metadata: {
+                subscription_external_id: input.localSubscriptionId,
+                tenant_id: input.tenantId,
+            },
+        }, input.idempotencyKey), (raw) => {
+            const result = this.checkout(raw);
+            if (result.amount !== input.amount ||
+                result.currency !== input.currency ||
+                result.localSubscriptionId !== input.localSubscriptionId)
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_CHECKOUT_MISMATCH', true);
+            return result;
+        });
+    }
+    async getCheckout(id) {
+        const result = this.checkout(await this.request(`/checkout_sessions/${(0, fintoc_http_client_1.fintocIdentifier)(id, 'cs')}`));
+        if (result.id !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_CHECKOUT_MISMATCH');
+        return result;
+    }
+    async getSubscription(id) {
+        const result = this.subscription(await this.request(`/subscriptions/${(0, fintoc_http_client_1.fintocIdentifier)(id, 'sub')}`));
+        if (result.id !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_SUBSCRIPTION_MISMATCH');
+        return result;
+    }
+    async cancelSubscription(id, key) {
+        (0, fintoc_http_client_1.billingIdempotencyKey)(key);
+        // A prior cancellation with an uncertain response is resolved by reading first.
+        const current = await this.getSubscription(id);
+        if (current.status === 'canceled' || current.status === 'cancelled')
+            return current;
+        return this.transport.mutation(() => this.request(`/subscriptions/${(0, fintoc_http_client_1.fintocIdentifier)(id, 'sub')}/cancel`, 'POST', {}, key), (raw) => {
+            const result = this.subscription(raw);
+            if (result.id !== id ||
+                result.customerId !== current.customerId ||
+                !['canceled', 'cancelled'].includes(result.status))
+                throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_CANCELLATION_MISMATCH');
+            return result;
+        });
+    }
+    async getInvoice(id) {
+        const result = this.invoice(await this.request(`/invoices/${(0, fintoc_http_client_1.fintocIdentifier)(id, 'inv')}`));
+        if (result.id !== id)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+        return result;
+    }
+    async listInvoices(subscriptionId, cursor) {
+        const query = new URLSearchParams({
+            subscription: (0, fintoc_http_client_1.fintocIdentifier)(subscriptionId, 'sub'),
+            limit: '50',
+        });
+        if (cursor)
+            query.set('starting_after', (0, fintoc_http_client_1.fintocIdentifier)(cursor, 'inv'));
+        const raw = await this.request(`/invoices?${query.toString()}`);
+        if (!Array.isArray(raw) || raw.length > 50)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_RESPONSE_INVALID');
+        const items = raw.map((item) => this.invoice(item));
+        if (items.some((item) => item.subscriptionId !== subscriptionId))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+        return {
+            items,
+            nextCursor: items.length === 50 ? items[items.length - 1].id : null,
+        };
+    }
+    verifyWebhook(rawBody, signature) {
+        this.credentials();
+        const secret = this.transport.webhookSecret();
+        if (!secret ||
+            !signature ||
+            !Buffer.isBuffer(rawBody) ||
+            rawBody.length > 1_048_576)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        const parts = signature.split(',').map((part) => part.trim().split('='));
+        const timestamps = parts.filter(([key]) => key === 't');
+        if (timestamps.length !== 1 || !/^\d+$/.test(timestamps[0][1] ?? ''))
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        const timestamp = Number(timestamps[0][1]);
+        const now = this.transport.now();
+        if (!Number.isSafeInteger(timestamp) ||
+            !Number.isFinite(now) ||
+            Math.abs(now / 1000 - timestamp) > 300)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_EXPIRED');
+        const expected = (0, node_crypto_1.createHmac)('sha256', secret)
+            .update(`${timestamp}.`)
+            .update(rawBody)
+            .digest();
+        const valid = parts.some(([key, value]) => key === 'v1' &&
+            /^[a-f0-9]{64}$/i.test(value ?? '') &&
+            (0, node_crypto_1.timingSafeEqual)(expected, Buffer.from(value, 'hex')));
+        if (!valid)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        let event;
+        try {
+            event = (0, fintoc_http_client_1.fintocObject)(JSON.parse(rawBody.toString('utf8')));
+        }
+        catch {
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_WEBHOOK_INVALID');
+        }
+        return {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(event.id, 'evt'),
+            type: (0, fintoc_http_client_1.fintocString)(event.type),
+            resourceId: (0, fintoc_http_client_1.fintocString)((0, fintoc_http_client_1.fintocObject)(event.data).id),
+            mode: this.mode(event.mode),
+        };
+    }
+    checkout(value) {
+        const data = (0, fintoc_http_client_1.fintocObject)(value);
+        const resource = data.subscription;
+        return {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(data.id, 'cs'),
+            redirectUrl: this.hostedUrl(data.redirect_url),
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            subscriptionId: resource ? (0, fintoc_http_client_1.fintocIdentifier)(resource, 'sub') : null,
+            status: (0, fintoc_http_client_1.fintocString)(data.status),
+            mode: this.mode(data.mode),
+            localSubscriptionId: (0, fintoc_http_client_1.fintocString)((0, fintoc_http_client_1.fintocObject)(data.metadata).subscription_external_id),
+            amount: (0, fintoc_http_client_1.fintocInteger)(data.amount),
+            currency: (0, fintoc_http_client_1.fintocString)(data.currency),
+        };
+    }
+    subscription(value) {
+        const data = (0, fintoc_http_client_1.fintocObject)(value);
+        return {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(data.id, 'sub'),
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            status: (0, fintoc_http_client_1.fintocString)(data.status),
+            mode: this.mode(data.mode),
+        };
+    }
+    invoice(value) {
+        const data = (0, fintoc_http_client_1.fintocObject)(value);
+        if (!Array.isArray(data.lines) ||
+            data.lines.length !== 1 ||
+            !Array.isArray(data.payments) ||
+            !['draft', 'open', 'paid', 'void'].includes(String(data.status)) ||
+            typeof data.external_payment !== 'boolean')
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_UNSUPPORTED');
+        const line = (0, fintoc_http_client_1.fintocObject)(data.lines[0]);
+        const amount = (0, fintoc_http_client_1.fintocInteger)(data.total);
+        const currency = (0, fintoc_http_client_1.fintocString)(data.currency);
+        const quantity = (0, fintoc_http_client_1.fintocInteger)(line.quantity);
+        const start = (0, fintoc_http_client_1.fintocString)(line.period_start), end = (0, fintoc_http_client_1.fintocString)(line.period_end);
+        const startAt = strictIsoInstant(start), endAt = strictIsoInstant(end);
+        if (quantity !== 1 ||
+            (0, fintoc_http_client_1.fintocInteger)(line.amount) !== amount ||
+            line.currency !== currency ||
+            startAt === null ||
+            endAt === null ||
+            startAt >= endAt)
+            throw new billing_core_1.SubscriptionGatewayError('BILLING_PROVIDER_INVOICE_MISMATCH');
+        const confirmed = data.status === 'paid' &&
+            data.external_payment === false &&
+            data.payments.some((value) => {
+                const payment = (0, fintoc_http_client_1.fintocObject)(value);
+                if (payment.status !== 'succeeded' ||
+                    payment.amount !== amount ||
+                    payment.currency !== currency)
+                    return false;
+                try {
+                    (0, fintoc_http_client_1.fintocIdentifier)(payment.payment_intent, 'pi');
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        return {
+            id: (0, fintoc_http_client_1.fintocIdentifier)(data.id, 'inv'),
+            subscriptionId: data.subscription
+                ? (0, fintoc_http_client_1.fintocIdentifier)(data.subscription, 'sub')
+                : null,
+            customerId: (0, fintoc_http_client_1.fintocIdentifier)(data.customer, 'cus'),
+            mode: this.mode(data.mode),
+            status: data.status,
+            amount,
+            currency,
+            externalPayment: data.external_payment,
+            paymentConfirmed: confirmed,
+            attemptCount: (0, fintoc_http_client_1.fintocInteger)(data.attempt_count),
+            periodStart: start,
+            periodEnd: end,
+            quantity,
+            hostedUrl: this.hostedUrl(data.hosted_invoice_url),
+        };
+    }
+    hostedUrl(value) {
+        return this.transport.hostedUrl(value);
+    }
+    returnUrl(kind) {
+        return this.transport.returnUrl(kind);
+    }
+    mode(value) {
+        return this.transport.mode(value);
+    }
+    credentials() {
+        return this.transport.credentials();
+    }
+    async request(path, method = 'GET', body, key) {
+        return this.transport.request(path, method, body, key);
+    }
+}
+exports.FintocSubscriptionGateway = FintocSubscriptionGateway;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FintocBillingProvider } from './fintoc-billing.provider';
+export type { FintocBillingProviderOptions, FintocRequestContext, FintocTransport, } from './fintoc-provider.options';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FintocBillingProvider = void 0;
+var fintoc_billing_provider_1 = require("./fintoc-billing.provider");
+Object.defineProperty(exports, "FintocBillingProvider", { enumerable: true, get: function () { return fintoc_billing_provider_1.FintocBillingProvider; } });

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@devly-cl/billing-fintoc",
+  "version": "0.1.0",
+  "description": "Fintoc billing adapter with injected transport and host policy.",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm --prefix ../.. run build:packages",
+    "prepublishOnly": "npm --prefix ../.. run verify:release && node ../../scripts/verify-release-publishable.mjs --package @devly-cl/billing-fintoc"
+  },
+  "dependencies": {
+    "@devly-cl/billing-core": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devly-cl/billing-packages.git",
+    "directory": "packages/billing-fintoc"
+  },
+  "bugs": {
+    "url": "https://github.com/devly-cl/billing-packages/issues"
+  },
+  "homepage": "https://github.com/devly-cl/billing-packages#readme"
+}