@peable.to/sdk 0.2.6-oxy-one.0 → 0.2.7

package/dist/cjs/contributions.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContributionsResource = void 0;
+// Browser entry (`@peable.to/sdk/contributions`) — organization contribution
+// management over a caller-supplied transport (the wallet's Oxy linked client).
+// Deliberately separate from the server entry, which carries the merchant-authed
+// service-token and billing-verification code (`node:crypto`) a browser or
+// React Native bundle must never pull in.
+var contributions_1 = require("./resources/contributions");
+Object.defineProperty(exports, "ContributionsResource", { enumerable: true, get: function () { return contributions_1.ContributionsResource; } });

package/dist/cjs/display.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPLAY_CURRENCIES = void 0;
+exports.isDisplayCurrency = isDisplayCurrency;
+exports.displayRatesAreFresh = displayRatesAreFresh;
+exports.readDisplayRates = readDisplayRates;
+exports.formatDisplayUnits = formatDisplayUnits;
+exports.convertDisplayAmount = convertDisplayAmount;
+/** Read-only display values. Never use these estimates to authorize a payment. */
+const core_1 = require("@fairco.in/core");
+exports.DISPLAY_CURRENCIES = ['USD', 'EUR', 'FAIR'];
+function isDisplayCurrency(value) {
+    return exports.DISPLAY_CURRENCIES.some((currency) => currency === value);
+}
+function fraction(value) {
+    const match = /^(0|[1-9][0-9]*)(?:\.([0-9]+))?(?:e([+-]?[0-9]+))?$/i.exec(value);
+    if (!match || value.length > 80)
+        throw new Error('Invalid display rate');
+    const exponent = Number(match[3] ?? 0) - (match[2]?.length ?? 0);
+    if (!Number.isSafeInteger(exponent) || Math.abs(exponent) > 30)
+        throw new Error('Invalid display rate');
+    let numerator = BigInt(`${match[1]}${match[2] ?? ''}`);
+    let denominator = 1n;
+    if (exponent >= 0)
+        numerator *= 10n ** BigInt(exponent);
+    else
+        denominator = 10n ** BigInt(-exponent);
+    if (numerator <= 0n)
+        throw new Error('Invalid display rate');
+    return { numerator, denominator };
+}
+function displayRatesAreFresh(rates, now = Date.now()) {
+    const observed = Date.parse(rates.observedAt);
+    const expires = Date.parse(rates.expiresAt);
+    return (Number.isFinite(observed) &&
+        observed <= now + 1000 &&
+        observed >= now - 120000 &&
+        expires > now &&
+        expires <= observed + 120000);
+}
+/** Uses the owning FairCoin source; no cached fallback after expiry or failure. */
+async function readDisplayRates(options = {}) {
+    const source = `${core_1.EXPLORER_BASE_URL}/api/price`;
+    const response = await (options.fetch ?? fetch)(source, {
+        signal: options.signal
+            ? AbortSignal.any([options.signal, AbortSignal.timeout(8000)])
+            : AbortSignal.timeout(8000),
+        redirect: 'error',
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok)
+        throw new Error('Exchange rate unavailable');
+    const body = await response.json();
+    if (!body || typeof body !== 'object' || !('price' in body) || !('updatedAt' in body))
+        throw new Error('Exchange rate unavailable');
+    const price = body.price;
+    if ((typeof price !== 'number' && typeof price !== 'string') ||
+        !('source' in body) ||
+        body.source !== 'wfair-base' ||
+        typeof body.updatedAt !== 'string')
+        throw new Error('Exchange rate unavailable');
+    const usdPerFair = String(price);
+    fraction(usdPerFair);
+    const observed = Date.parse(body.updatedAt);
+    if (!Number.isFinite(observed))
+        throw new Error('Exchange rate unavailable');
+    const rates = {
+        usdPerFair,
+        // The public Explorer supplies USD only. Keep USD/FAIR usable without
+        // pretending the USD rate also applies to EUR or inventing a cross rate.
+        eurPerFair: null,
+        source,
+        observedAt: new Date(observed).toISOString(),
+        expiresAt: new Date(observed + 120000).toISOString(),
+    };
+    if (!displayRatesAreFresh(rates, options.now ?? Date.now()))
+        throw new Error('Exchange rate unavailable');
+    return rates;
+}
+/** Decimal string formatting preserves all eight FAIR decimals and large values. */
+function formatDisplayUnits(units, decimals, currency) {
+    if (units < 0n || !Number.isInteger(decimals) || decimals < 0 || decimals > 8)
+        throw new Error('Invalid display amount');
+    const digits = units.toString().padStart(decimals + 1, '0');
+    return `${decimals ? `${digits.slice(0, -decimals)}.${digits.slice(-decimals)}` : digits} ${currency}`;
+}
+/** Round half up once, at the destination currency's precision. */
+function convertDisplayAmount(input) {
+    if (!/^(0|[1-9][0-9]*)$/.test(input.units) || input.units.length > 30)
+        throw new Error('Invalid display amount');
+    const units = BigInt(input.units);
+    const sourceScale = input.currency === 'FAIR' ? 100000000n : 100n;
+    const targetDecimals = input.displayCurrency === 'FAIR' ? 8 : 2;
+    if (input.currency === input.displayCurrency || units === 0n)
+        return formatDisplayUnits(units === 0n ? 0n : units, targetDecimals, input.displayCurrency);
+    if (!input.rates || !displayRatesAreFresh(input.rates, input.now))
+        return null;
+    const destinationRate = input.displayCurrency === 'EUR' ? input.rates.eurPerFair : input.rates.usdPerFair;
+    if (destinationRate === null)
+        return null;
+    const usd = fraction(input.rates.usdPerFair);
+    const destination = input.displayCurrency === 'FAIR'
+        ? { numerator: 1n, denominator: 1n }
+        : fraction(destinationRate);
+    const numerator = units *
+        destination.numerator *
+        10n ** BigInt(targetDecimals) *
+        (input.currency === 'USD' ? usd.denominator : 1n);
+    const denominator = sourceScale * destination.denominator * (input.currency === 'USD' ? usd.numerator : 1n);
+    return formatDisplayUnits((numerator * 2n + denominator) / (2n * denominator), targetDecimals, input.displayCurrency);
+}

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebhooksResource = exports.WEBHOOK_SIGNATURE_HEADER = exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = exports.Peable = void 0;
+exports.ContributionsResource = exports.WebhooksResource = exports.WEBHOOK_SIGNATURE_HEADER = exports.PeableSignatureVerificationError = exports.PeableApiError = exports.PeablePermissionError = exports.PeableInvalidRequestError = exports.PeableAuthenticationError = exports.PeableError = exports.DEFAULT_OXY_API_URL = exports.DEFAULT_GATEWAY_BASE_URL = exports.Peable = void 0;
 const billing_1 = require("./resources/billing");
 // Server entry (`@peable.to/sdk`) — the merchant-authed SDK. Configured with a
 // confidential `ApplicationCredential` (`{publicKey, secret}`), from which it
@@ -70,3 +70,5 @@ Object.defineProperty(exports, "PeableSignatureVerificationError", { enumerable:
 var webhooks_2 = require("./resources/webhooks");
 Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", { enumerable: true, get: function () { return webhooks_2.WEBHOOK_SIGNATURE_HEADER; } });
 Object.defineProperty(exports, "WebhooksResource", { enumerable: true, get: function () { return webhooks_2.WebhooksResource; } });
+var contributions_1 = require("./resources/contributions");
+Object.defineProperty(exports, "ContributionsResource", { enumerable: true, get: function () { return contributions_1.ContributionsResource; } });

package/dist/cjs/resources/billing.js

@@ -25,6 +25,13 @@ class BillingResource {
             idempotencyKey: options.idempotencyKey,
         });
     }
+    /** Opens a new expiring FAIR payment for one monthly period. Never auto-debits. */
+    renewSubscription(ref, params, options) {
+        return this.client.request('POST', `/v1/billing/subscriptions/${encodeURIComponent(ref)}/renew`, {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
     createPortalSession(params, options) {
         return this.client.request('POST', '/v1/billing/portal_sessions', {
             body: params,
@@ -34,6 +41,12 @@ class BillingResource {
     retrieveCheckout(ref) {
         return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`);
     }
+    /** Reads existing operation state only, even after quote/session expiry.
+     * Missing/pending/indeterminate never authorizes another create or cancellation. */
+    retrieveCheckoutOperation(params) {
+        const { idempotencyKey, ...query } = params;
+        return this.client.request('GET', `/v1/billing/checkout_operations/${encodeURIComponent(idempotencyKey)}`, { query });
+    }
     async createTaxQuote(params) {
         if (!this.taxQuoteAuthorityKeys || Object.keys(this.taxQuoteAuthorityKeys).length === 0)
             throw new Error('Peable: tax quote authority verification is unconfigured');
@@ -90,7 +103,7 @@ class BillingResource {
                     !Number.isFinite(Date.parse(quote.quotedAt)) ||
                     Date.parse(quote.quotedAt) > Date.now() ||
                     !Number.isFinite(Date.parse(quote.expiresAt)) ||
-                    Date.parse(quote.expiresAt) <= Date.now() ||
+                    Date.parse(quote.expiresAt) <= Date.parse(quote.quotedAt) ||
                     Date.parse(quote.expiresAt) > Date.parse(authority.invoice.expiresAt))
                     throw new Error('Invalid quote');
             }
@@ -98,6 +111,25 @@ class BillingResource {
             if (key.asymmetricKeyType !== 'ed25519' ||
                 !(0, node_crypto_1.verify)(null, Buffer.from((0, shared_types_1.canonicalBillingAuthority)(authority), 'utf8'), key, Buffer.from(authority.signature.value, 'base64url')))
                 throw new Error('Invalid signature');
+            // The FX quote bounds the payment, not delivery of its observation. A
+            // delayed webhook must remain recoverable after the original quote expires.
+            if (authority.method === 'faircoin') {
+                const paid = await this.retrievePaidInvoice(subscriptionRef, invoiceRef);
+                // biome-ignore lint/style/noNonNullAssertion: FairCoin quote presence and bounds were verified above before signature verification.
+                const quote = authority.invoice.faircoinQuote;
+                const paidAt = Date.parse(paid.paidAt);
+                if (paid.invoiceId !== invoiceRef ||
+                    paid.providerSubscriptionId !== subscriptionRef ||
+                    paid.paymentIntentId !== authority.source.paymentIntentId ||
+                    paid.providerCustomerId !== authority.source.customerId ||
+                    paid.providerPriceId !== authority.source.priceId ||
+                    paid.storeId !== authority.invoice.context.payerAccountId ||
+                    !Number.isFinite(paidAt) ||
+                    paidAt > Date.now() ||
+                    paidAt < Date.parse(quote.quotedAt) ||
+                    paidAt >= Date.parse(quote.expiresAt))
+                    throw new Error('Payment outside signed quote');
+            }
         }
         catch {
             throw new Error('Peable: invoice authority verification failed');

package/dist/cjs/resources/contributions.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContributionsResource = void 0;
+const contracts_1 = require("@peable.to/contracts");
+/** Human management uses an Oxy linked-client transport; never a merchant service token. */
+class ContributionsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    path(scope) {
+        return `/v1/organizations/${encodeURIComponent(scope.organizationId)}/applications/${encodeURIComponent(scope.applicationId)}/contributions`;
+    }
+    async create(scope, body, idempotencyKey) {
+        return contracts_1.contributionLinkSchema.parse(await this.client.request('POST', this.path(scope), {
+            query: { environment: scope.environment },
+            body: contracts_1.createContributionSchema.parse(body),
+            idempotencyKey: contracts_1.contributionOperationKeySchema.parse(idempotencyKey),
+        }));
+    }
+    async list(scope, page = {}) {
+        return contracts_1.contributionListSchema.parse(await this.client.request('GET', this.path(scope), {
+            query: { environment: scope.environment, ...page },
+        }));
+    }
+    async *iterate(scope) {
+        let cursor;
+        const seen = new Set();
+        do {
+            const page = await this.list(scope, cursor ? { cursor } : {});
+            yield* page.items;
+            cursor = page.nextCursor ?? undefined;
+            if (cursor) {
+                if (seen.has(cursor))
+                    throw new Error('Repeated contribution cursor');
+                seen.add(cursor);
+            }
+        } while (cursor);
+    }
+    async setActive(scope, id, active) {
+        return contracts_1.contributionLinkSchema.parse(await this.client.request('PATCH', `${this.path(scope)}/${encodeURIComponent(id)}`, {
+            query: { environment: scope.environment },
+            body: { active },
+        }));
+    }
+    async collections(scope, id, page = {}) {
+        return contracts_1.contributionCollectionListSchema.parse(await this.client.request('GET', `${this.path(scope)}/${encodeURIComponent(id)}/collections`, { query: { environment: scope.environment, ...page } }));
+    }
+}
+exports.ContributionsResource = ContributionsResource;

package/dist/cjs/resources/webhooks.js

@@ -36,6 +36,7 @@ function isWebhookEventShape(value) {
     const valid = typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
+        // biome-ignore lint/suspicious/noPrototypeBuiltins: the published SDK targets ES2020, and Object.hasOwn is ES2022
         Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&

package/dist/esm/contributions.js

@@ -0,0 +1,6 @@
+// Browser entry (`@peable.to/sdk/contributions`) — organization contribution
+// management over a caller-supplied transport (the wallet's Oxy linked client).
+// Deliberately separate from the server entry, which carries the merchant-authed
+// service-token and billing-verification code (`node:crypto`) a browser or
+// React Native bundle must never pull in.
+export { ContributionsResource } from './resources/contributions.js';

package/dist/esm/display.js

@@ -0,0 +1,103 @@
+/** Read-only display values. Never use these estimates to authorize a payment. */
+import { EXPLORER_BASE_URL } from '@fairco.in/core';
+export const DISPLAY_CURRENCIES = ['USD', 'EUR', 'FAIR'];
+export function isDisplayCurrency(value) {
+    return DISPLAY_CURRENCIES.some((currency) => currency === value);
+}
+function fraction(value) {
+    const match = /^(0|[1-9][0-9]*)(?:\.([0-9]+))?(?:e([+-]?[0-9]+))?$/i.exec(value);
+    if (!match || value.length > 80)
+        throw new Error('Invalid display rate');
+    const exponent = Number(match[3] ?? 0) - (match[2]?.length ?? 0);
+    if (!Number.isSafeInteger(exponent) || Math.abs(exponent) > 30)
+        throw new Error('Invalid display rate');
+    let numerator = BigInt(`${match[1]}${match[2] ?? ''}`);
+    let denominator = 1n;
+    if (exponent >= 0)
+        numerator *= 10n ** BigInt(exponent);
+    else
+        denominator = 10n ** BigInt(-exponent);
+    if (numerator <= 0n)
+        throw new Error('Invalid display rate');
+    return { numerator, denominator };
+}
+export function displayRatesAreFresh(rates, now = Date.now()) {
+    const observed = Date.parse(rates.observedAt);
+    const expires = Date.parse(rates.expiresAt);
+    return (Number.isFinite(observed) &&
+        observed <= now + 1000 &&
+        observed >= now - 120000 &&
+        expires > now &&
+        expires <= observed + 120000);
+}
+/** Uses the owning FairCoin source; no cached fallback after expiry or failure. */
+export async function readDisplayRates(options = {}) {
+    const source = `${EXPLORER_BASE_URL}/api/price`;
+    const response = await (options.fetch ?? fetch)(source, {
+        signal: options.signal
+            ? AbortSignal.any([options.signal, AbortSignal.timeout(8000)])
+            : AbortSignal.timeout(8000),
+        redirect: 'error',
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok)
+        throw new Error('Exchange rate unavailable');
+    const body = await response.json();
+    if (!body || typeof body !== 'object' || !('price' in body) || !('updatedAt' in body))
+        throw new Error('Exchange rate unavailable');
+    const price = body.price;
+    if ((typeof price !== 'number' && typeof price !== 'string') ||
+        !('source' in body) ||
+        body.source !== 'wfair-base' ||
+        typeof body.updatedAt !== 'string')
+        throw new Error('Exchange rate unavailable');
+    const usdPerFair = String(price);
+    fraction(usdPerFair);
+    const observed = Date.parse(body.updatedAt);
+    if (!Number.isFinite(observed))
+        throw new Error('Exchange rate unavailable');
+    const rates = {
+        usdPerFair,
+        // The public Explorer supplies USD only. Keep USD/FAIR usable without
+        // pretending the USD rate also applies to EUR or inventing a cross rate.
+        eurPerFair: null,
+        source,
+        observedAt: new Date(observed).toISOString(),
+        expiresAt: new Date(observed + 120000).toISOString(),
+    };
+    if (!displayRatesAreFresh(rates, options.now ?? Date.now()))
+        throw new Error('Exchange rate unavailable');
+    return rates;
+}
+/** Decimal string formatting preserves all eight FAIR decimals and large values. */
+export function formatDisplayUnits(units, decimals, currency) {
+    if (units < 0n || !Number.isInteger(decimals) || decimals < 0 || decimals > 8)
+        throw new Error('Invalid display amount');
+    const digits = units.toString().padStart(decimals + 1, '0');
+    return `${decimals ? `${digits.slice(0, -decimals)}.${digits.slice(-decimals)}` : digits} ${currency}`;
+}
+/** Round half up once, at the destination currency's precision. */
+export function convertDisplayAmount(input) {
+    if (!/^(0|[1-9][0-9]*)$/.test(input.units) || input.units.length > 30)
+        throw new Error('Invalid display amount');
+    const units = BigInt(input.units);
+    const sourceScale = input.currency === 'FAIR' ? 100000000n : 100n;
+    const targetDecimals = input.displayCurrency === 'FAIR' ? 8 : 2;
+    if (input.currency === input.displayCurrency || units === 0n)
+        return formatDisplayUnits(units === 0n ? 0n : units, targetDecimals, input.displayCurrency);
+    if (!input.rates || !displayRatesAreFresh(input.rates, input.now))
+        return null;
+    const destinationRate = input.displayCurrency === 'EUR' ? input.rates.eurPerFair : input.rates.usdPerFair;
+    if (destinationRate === null)
+        return null;
+    const usd = fraction(input.rates.usdPerFair);
+    const destination = input.displayCurrency === 'FAIR'
+        ? { numerator: 1n, denominator: 1n }
+        : fraction(destinationRate);
+    const numerator = units *
+        destination.numerator *
+        10n ** BigInt(targetDecimals) *
+        (input.currency === 'USD' ? usd.denominator : 1n);
+    const denominator = sourceScale * destination.denominator * (input.currency === 'USD' ? usd.numerator : 1n);
+    return formatDisplayUnits((numerator * 2n + denominator) / (2n * denominator), targetDecimals, input.displayCurrency);
+}

package/dist/esm/index.js

@@ -56,3 +56,4 @@ export class Peable {
 export { DEFAULT_GATEWAY_BASE_URL, DEFAULT_OXY_API_URL } from './core/config.js';
 export { PeableError, PeableAuthenticationError, PeableInvalidRequestError, PeablePermissionError, PeableApiError, PeableSignatureVerificationError, } from './core/errors.js';
 export { WEBHOOK_SIGNATURE_HEADER, WebhooksResource } from './resources/webhooks.js';
+export { ContributionsResource } from './resources/contributions.js';

package/dist/esm/resources/billing.js

@@ -22,6 +22,13 @@ export class BillingResource {
             idempotencyKey: options.idempotencyKey,
         });
     }
+    /** Opens a new expiring FAIR payment for one monthly period. Never auto-debits. */
+    renewSubscription(ref, params, options) {
+        return this.client.request('POST', `/v1/billing/subscriptions/${encodeURIComponent(ref)}/renew`, {
+            body: params,
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
     createPortalSession(params, options) {
         return this.client.request('POST', '/v1/billing/portal_sessions', {
             body: params,
@@ -31,6 +38,12 @@ export class BillingResource {
     retrieveCheckout(ref) {
         return this.client.request('GET', `/v1/billing/checkout_sessions/${encodeURIComponent(ref)}`);
     }
+    /** Reads existing operation state only, even after quote/session expiry.
+     * Missing/pending/indeterminate never authorizes another create or cancellation. */
+    retrieveCheckoutOperation(params) {
+        const { idempotencyKey, ...query } = params;
+        return this.client.request('GET', `/v1/billing/checkout_operations/${encodeURIComponent(idempotencyKey)}`, { query });
+    }
     async createTaxQuote(params) {
         if (!this.taxQuoteAuthorityKeys || Object.keys(this.taxQuoteAuthorityKeys).length === 0)
             throw new Error('Peable: tax quote authority verification is unconfigured');
@@ -87,7 +100,7 @@ export class BillingResource {
                     !Number.isFinite(Date.parse(quote.quotedAt)) ||
                     Date.parse(quote.quotedAt) > Date.now() ||
                     !Number.isFinite(Date.parse(quote.expiresAt)) ||
-                    Date.parse(quote.expiresAt) <= Date.now() ||
+                    Date.parse(quote.expiresAt) <= Date.parse(quote.quotedAt) ||
                     Date.parse(quote.expiresAt) > Date.parse(authority.invoice.expiresAt))
                     throw new Error('Invalid quote');
             }
@@ -95,6 +108,25 @@ export class BillingResource {
             if (key.asymmetricKeyType !== 'ed25519' ||
                 !verify(null, Buffer.from(canonicalBillingAuthority(authority), 'utf8'), key, Buffer.from(authority.signature.value, 'base64url')))
                 throw new Error('Invalid signature');
+            // The FX quote bounds the payment, not delivery of its observation. A
+            // delayed webhook must remain recoverable after the original quote expires.
+            if (authority.method === 'faircoin') {
+                const paid = await this.retrievePaidInvoice(subscriptionRef, invoiceRef);
+                // biome-ignore lint/style/noNonNullAssertion: FairCoin quote presence and bounds were verified above before signature verification.
+                const quote = authority.invoice.faircoinQuote;
+                const paidAt = Date.parse(paid.paidAt);
+                if (paid.invoiceId !== invoiceRef ||
+                    paid.providerSubscriptionId !== subscriptionRef ||
+                    paid.paymentIntentId !== authority.source.paymentIntentId ||
+                    paid.providerCustomerId !== authority.source.customerId ||
+                    paid.providerPriceId !== authority.source.priceId ||
+                    paid.storeId !== authority.invoice.context.payerAccountId ||
+                    !Number.isFinite(paidAt) ||
+                    paidAt > Date.now() ||
+                    paidAt < Date.parse(quote.quotedAt) ||
+                    paidAt >= Date.parse(quote.expiresAt))
+                    throw new Error('Payment outside signed quote');
+            }
         }
         catch {
             throw new Error('Peable: invoice authority verification failed');

package/dist/esm/resources/contributions.js

@@ -0,0 +1,45 @@
+import { contributionLinkSchema, contributionListSchema, contributionCollectionListSchema, createContributionSchema, contributionOperationKeySchema, } from '@peable.to/contracts';
+/** Human management uses an Oxy linked-client transport; never a merchant service token. */
+export class ContributionsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    path(scope) {
+        return `/v1/organizations/${encodeURIComponent(scope.organizationId)}/applications/${encodeURIComponent(scope.applicationId)}/contributions`;
+    }
+    async create(scope, body, idempotencyKey) {
+        return contributionLinkSchema.parse(await this.client.request('POST', this.path(scope), {
+            query: { environment: scope.environment },
+            body: createContributionSchema.parse(body),
+            idempotencyKey: contributionOperationKeySchema.parse(idempotencyKey),
+        }));
+    }
+    async list(scope, page = {}) {
+        return contributionListSchema.parse(await this.client.request('GET', this.path(scope), {
+            query: { environment: scope.environment, ...page },
+        }));
+    }
+    async *iterate(scope) {
+        let cursor;
+        const seen = new Set();
+        do {
+            const page = await this.list(scope, cursor ? { cursor } : {});
+            yield* page.items;
+            cursor = page.nextCursor ?? undefined;
+            if (cursor) {
+                if (seen.has(cursor))
+                    throw new Error('Repeated contribution cursor');
+                seen.add(cursor);
+            }
+        } while (cursor);
+    }
+    async setActive(scope, id, active) {
+        return contributionLinkSchema.parse(await this.client.request('PATCH', `${this.path(scope)}/${encodeURIComponent(id)}`, {
+            query: { environment: scope.environment },
+            body: { active },
+        }));
+    }
+    async collections(scope, id, page = {}) {
+        return contributionCollectionListSchema.parse(await this.client.request('GET', `${this.path(scope)}/${encodeURIComponent(id)}/collections`, { query: { environment: scope.environment, ...page } }));
+    }
+}

package/dist/esm/resources/webhooks.js

@@ -33,6 +33,7 @@ function isWebhookEventShape(value) {
     const valid = typeof candidate.id === 'string' &&
         candidate.object === 'event' &&
         typeof candidate.type === 'string' &&
+        // biome-ignore lint/suspicious/noPrototypeBuiltins: the published SDK targets ES2020, and Object.hasOwn is ES2022
         Object.prototype.hasOwnProperty.call(WEBHOOK_EVENT_TYPES, candidate.type) &&
         typeof candidate.created === 'string' &&
         typeof candidate.data === 'object' &&

package/dist/types/contributions.d.ts

@@ -0,0 +1,2 @@
+export { ContributionsResource, type ContributionScope } from './resources/contributions';
+export type { RestClient, RestClientRequestOptions } from './core/client';

package/dist/types/display.d.ts

@@ -0,0 +1,29 @@
+export declare const DISPLAY_CURRENCIES: readonly ["USD", "EUR", "FAIR"];
+export type DisplayCurrency = (typeof DISPLAY_CURRENCIES)[number];
+export interface DisplayRates {
+    /** Currency units per FAIR, as exact decimal strings. */
+    usdPerFair: string;
+    /** Null when the owning source does not supply a EUR quote. */
+    eurPerFair: string | null;
+    source: string;
+    observedAt: string;
+    expiresAt: string;
+}
+export declare function isDisplayCurrency(value: unknown): value is DisplayCurrency;
+export declare function displayRatesAreFresh(rates: DisplayRates, now?: number): boolean;
+/** Uses the owning FairCoin source; no cached fallback after expiry or failure. */
+export declare function readDisplayRates(options?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    now?: number;
+}): Promise<DisplayRates>;
+/** Decimal string formatting preserves all eight FAIR decimals and large values. */
+export declare function formatDisplayUnits(units: bigint, decimals: number, currency: string): string;
+/** Round half up once, at the destination currency's precision. */
+export declare function convertDisplayAmount(input: {
+    units: string;
+    currency: 'USD' | 'FAIR';
+    displayCurrency: DisplayCurrency;
+    rates?: DisplayRates | null;
+    now?: number;
+}): string | null;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { BillingResource } from './resources/billing';
 export type { BillingRequestOptions } from './resources/billing';
-export type { CreateBillingTaxQuoteParams, BillingTaxQuote, BillingInvoiceAuthoritySource, BillingFinalInvoice, BillingFinalInvoiceAuthority, BillingFaircoinRenewalChoice, BillingFaircoinRenewalConsent, BillingFaircoinRenewalRevocation, BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams, } from '@peable.to/shared-types';
+export type { CreateBillingTaxQuoteParams, BillingTaxQuote, BillingInvoiceAuthoritySource, BillingFinalInvoice, BillingFinalInvoiceAuthority, BillingFaircoinRenewalChoice, BillingFaircoinRenewalConsent, BillingFaircoinRenewalRevocation, BillingObservation, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationSource, BillingCheckoutOperationRecovery, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams, } from '@peable.to/shared-types';
 import { type PeableConfig } from './core/config';
 import { PaymentIntentsResource } from './resources/paymentIntents';
 import { PaymentLinksResource } from './resources/paymentLinks';
@@ -59,3 +59,6 @@ export type { CreateTransferParams, ReverseTransferParams, TransferList, } from
 export type { PaymentLinkListParams, PaymentLinkList, UpdatePaymentLinkParams, } from './resources/paymentLinks';
 export { WEBHOOK_SIGNATURE_HEADER, WebhooksResource } from './resources/webhooks';
 export type { ConstructEventOptions } from './resources/webhooks';
+export { ContributionsResource } from './resources/contributions';
+export type { ContributionScope, CreateContribution, ContributionLink, ContributionDetails, } from './resources/contributions';
+export type { BillingFaircoinFxQuote } from '@peable.to/shared-types';

package/dist/types/resources/billing.d.ts

@@ -1,4 +1,4 @@
-import type { BillingTaxQuote, CreateBillingTaxQuoteParams, BillingFinalInvoiceAuthority, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
+import type { BillingTaxQuote, RetrieveBillingCheckoutOperationParams, BillingCheckoutOperationRecovery, CreateBillingTaxQuoteParams, BillingFinalInvoiceAuthority, BillingCustomer, BillingHostedSession, BillingCheckoutSession, BillingCheckoutObservation, BillingPaidInvoice, BillingInvoiceState, BillingSubscription, CreateBillingCheckoutParams, CreateBillingPortalParams, EnsureBillingCustomerParams } from '@peable.to/shared-types';
 import type { RestClient } from '../core/client';
 export interface BillingRequestOptions {
     idempotencyKey: string;
@@ -14,8 +14,13 @@ export declare class BillingResource {
      * its pinned authority and retains immutable evidence before creating a session.
      * Existing callers without a quote remain on their explicitly enabled legacy path. */
     createCheckoutSession(params: CreateBillingCheckoutParams, options: BillingRequestOptions): Promise<BillingCheckoutSession>;
+    /** Opens a new expiring FAIR payment for one monthly period. Never auto-debits. */
+    renewSubscription(ref: string, params: CreateBillingCheckoutParams, options: BillingRequestOptions): Promise<BillingCheckoutSession>;
     createPortalSession(params: CreateBillingPortalParams, options: BillingRequestOptions): Promise<BillingHostedSession>;
     retrieveCheckout(ref: string): Promise<BillingCheckoutObservation>;
+    /** Reads existing operation state only, even after quote/session expiry.
+     * Missing/pending/indeterminate never authorizes another create or cancellation. */
+    retrieveCheckoutOperation(params: RetrieveBillingCheckoutOperationParams): Promise<BillingCheckoutOperationRecovery>;
     createTaxQuote(params: CreateBillingTaxQuoteParams): Promise<BillingTaxQuote>;
     retrieveFinalInvoiceAuthority(subscriptionRef: string, invoiceRef: string): Promise<BillingFinalInvoiceAuthority>;
     retrievePaidInvoice(subscriptionRef: string, invoiceRef: string): Promise<BillingPaidInvoice>;

package/dist/types/resources/contributions.d.ts

@@ -0,0 +1,100 @@
+import { type CreateContribution } from '@peable.to/contracts';
+import type { RestClient } from '../core/client';
+export interface ContributionScope {
+    organizationId: string;
+    applicationId: string;
+    environment: 'development' | 'staging' | 'production';
+}
+/** Human management uses an Oxy linked-client transport; never a merchant service token. */
+export declare class ContributionsResource {
+    private readonly client;
+    constructor(client: RestClient);
+    private path;
+    create(scope: ContributionScope, body: CreateContribution, idempotencyKey: string): Promise<{
+        id: string;
+        amount: string;
+        currency: "FAIR";
+        network: "mainnet" | "testnet";
+        active: boolean;
+        url: string;
+        contribution: {
+            organizationId: string;
+            purpose: string;
+            amountMode: "fixed" | "free";
+            expiresAt: string | null;
+        };
+        createdAt: string;
+    }>;
+    list(scope: ContributionScope, page?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: {
+            id: string;
+            amount: string;
+            currency: "FAIR";
+            network: "mainnet" | "testnet";
+            active: boolean;
+            url: string;
+            contribution: {
+                organizationId: string;
+                purpose: string;
+                amountMode: "fixed" | "free";
+                expiresAt: string | null;
+            };
+            createdAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
+    iterate(scope: ContributionScope): AsyncGenerator<{
+        id: string;
+        amount: string;
+        currency: "FAIR";
+        network: "mainnet" | "testnet";
+        active: boolean;
+        url: string;
+        contribution: {
+            organizationId: string;
+            purpose: string;
+            amountMode: "fixed" | "free";
+            expiresAt: string | null;
+        };
+        createdAt: string;
+    }, void, unknown>;
+    setActive(scope: ContributionScope, id: string, active: boolean): Promise<{
+        id: string;
+        amount: string;
+        currency: "FAIR";
+        network: "mainnet" | "testnet";
+        active: boolean;
+        url: string;
+        contribution: {
+            organizationId: string;
+            purpose: string;
+            amountMode: "fixed" | "free";
+            expiresAt: string | null;
+        };
+        createdAt: string;
+    }>;
+    collections(scope: ContributionScope, id: string, page?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: {
+            id: string;
+            amount: string;
+            currency: "FAIR";
+            status: string;
+            createdAt: string;
+            refundCapability: "unsupported_non_custodial";
+            refunds: {
+                id: string;
+                amount: string;
+                status: string;
+                createdAt: string;
+            }[];
+        }[];
+        nextCursor: string | null;
+    }>;
+}
+export type { CreateContribution, ContributionLink, ContributionDetails, } from '@peable.to/contracts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/sdk",
-  "version": "0.2.6-oxy-one.0",
+  "version": "0.2.7",
   "description": "Peable SDK — a Stripe-ergonomics TypeScript client over the Peable Gateway REST + realtime contract. Server entry (`@peable.to/sdk`) mints Oxy service tokens from an ApplicationCredential and exposes paymentIntents/paymentLinks/checkout.sessions/webhooks; browser entry (`@peable.to/sdk/checkout`) is the anonymous payer-side client core.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -9,8 +9,7 @@
   "sideEffects": false,
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "tag": "oxy-one"
+    "registry": "https://registry.npmjs.org/"
   },
   "exports": {
     ".": {
@@ -37,7 +36,26 @@
       },
       "default": "./dist/esm/checkout.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./display": {
+      "react-native": "./dist/esm/display.js",
+      "import": {
+        "types": "./dist/types/display.d.ts",
+        "default": "./dist/esm/display.js"
+      }
+    },
+    "./contributions": {
+      "react-native": "./dist/esm/contributions.js",
+      "import": {
+        "types": "./dist/types/contributions.d.ts",
+        "default": "./dist/esm/contributions.js"
+      },
+      "require": {
+        "types": "./dist/types/contributions.d.ts",
+        "default": "./dist/cjs/contributions.js"
+      },
+      "default": "./dist/esm/contributions.js"
+    }
   },
   "files": [
     "dist"
@@ -72,9 +90,11 @@
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
-    "@peable.to/shared-types": "0.3.3-oxy-one.0",
+    "@peable.to/shared-types": "0.3.4",
     "qrcode-generator": "^2.0.4",
-    "socket.io-client": "^4.8.3"
+    "socket.io-client": "^4.8.3",
+    "@peable.to/contracts": "0.1.0",
+    "@fairco.in/core": "0.5.0"
   },
   "devDependencies": {
     "typescript": "~5.9.2",