@peable.to/contracts 1.0.0 → 1.2.0

package/dist/cjs/vocabulary/dashboard.js

@@ -0,0 +1,68 @@
+"use strict";
+// What a signed-in person may do in Orbit — the ONE map from a dashboard
+// action to the Oxy application permission it needs. Zod-free. The gateway
+// gates every `/v1/dashboard/applications/:id/*` and contribution route on it
+// (a refusal is `permission_required`, `param` naming the permission), and
+// Orbit hides or disables what the person lacks with the SAME map, so the two
+// can never disagree about who may do what.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_UPLOAD_ACTION = exports.DASHBOARD_PERMISSIONS = void 0;
+exports.allowsDashboardAction = allowsDashboardAction;
+/**
+ * The permissions are oxy-api's own APPLICATION vocabulary
+ * (`packages/api/src/utils/accountRoles.ts`, `APPLICATION_PERMISSIONS`): Oxy
+ * resolves the person's role, grants and revokes on the account that owns the
+ * application into `callerMembership.permissions`, and that list — from
+ * `apps.get` on the gateway, from `apps.list` in Orbit — is the whole answer.
+ * Peable never reads a role name and keeps no membership copy.
+ */
+exports.DASHBOARD_PERMISSIONS = {
+    /**
+     * Every read, the searches and a report run (it materialises the same rows a
+     * download streams). oxy-api answers an application only to a holder of
+     * `app:read`, so this is membership itself.
+     */
+    read: 'app:read',
+    /**
+     * The integration's configuration: branding and customer emails, the
+     * catalog, checkout sessions and payment links, contribution links, payment
+     * methods and wallet domains, a business logo.
+     */
+    configure: 'app:update',
+    /** Webhook endpoints and their signing secrets, test events, redelivery. */
+    webhooks: 'webhooks:update',
+    /**
+     * Money and who receives it: the merchant registration (its watch-only key
+     * and confirmations), the provider account and its onboarding and identity
+     * documents, payouts, sellers and transfers, disputes and their evidence, the
+     * billing engine, and every Peable Tax change or decision.
+     */
+    money: 'billing:manage',
+    /** Peable Tax reads and previews (ADR 0011, ADR 0020). */
+    taxRead: 'billing:read',
+};
+/**
+ * A permission that CONTAINS another: whoever may manage billing may read it.
+ * Stated once so the gateway and Orbit apply the same containment.
+ */
+const IMPLIED_BY = {
+    'billing:read': 'billing:manage',
+};
+/** Whether `held` (Oxy's `callerMembership.permissions`) allows `action`. */
+function allowsDashboardAction(held, action) {
+    const required = exports.DASHBOARD_PERMISSIONS[action];
+    const container = IMPLIED_BY[required];
+    return held.includes(required) || (container !== undefined && held.includes(container));
+}
+/**
+ * Uploading a file is the first half of USING it, so it needs what the use
+ * needs: a logo is configuration, everything else is evidence or identity for
+ * money (a dispute, the provider account, Peable Tax).
+ */
+exports.FILE_UPLOAD_ACTION = {
+    business_logo: 'configure',
+    dispute_evidence: 'money',
+    identity_document: 'money',
+    additional_verification: 'money',
+    tax_document: 'money',
+};

package/dist/cjs/vocabulary/errors.js

@@ -162,8 +162,9 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     // The dashboard routes (`/v1/dashboard/*`, Orbit): the signed-in person, not a credential.
     merchant_missing: 'The application has no merchant in this environment yet; register one (Orbit shows "Set up payments").',
     application_membership_required: 'The signed-in Oxy account is not a member of the account that owns this application.',
-    permission_required: 'The member lacks an Oxy permission this needs; `param` names it (`billing:read`, `billing:manage`). An owner grants it in Oxy Console.',
-    membership_unavailable: 'Oxy could not be asked whether the signed-in person is a member of this application; retry.',
+    account_membership_required: "The signed-in Oxy account is not a member of the Oxy account the path names (a contribution route's organization).",
+    permission_required: 'The member lacks the Oxy permission this action needs; `param` names it (`app:update`, `webhooks:update`, `billing:read`, `billing:manage`). An owner grants it in Oxy Console.',
+    membership_unavailable: 'Oxy could not be asked what the signed-in person may do on this application or account; retry.',
     session_invalid: 'Oxy no longer accepts the signed-in session; sign in again.',
 };
 /** Every error code, sorted. */

package/dist/cjs/vocabulary/identity.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PEABLE_SERVICE_AUDIENCE = exports.PEABLE_OXY_APPLICATION_ID = void 0;
+/**
+ * Peable's own Oxy application: the identity the gateway runs as (`OxyServer`'s
+ * `applicationId`) and the one an Oxy service addresses when it calls the
+ * gateway. One constant, so the gateway's accepted audience and the SDK's
+ * requested one cannot name two different applications.
+ */
+exports.PEABLE_OXY_APPLICATION_ID = '6a2f851751b784a86fd0e958';
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+exports.PEABLE_SERVICE_AUDIENCE = `oxy-service:${exports.PEABLE_OXY_APPLICATION_ID}`;

package/dist/cjs/vocabulary/index.js

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // package root, which constructs every schema at load.
 __exportStar(require("./billingPortal"), exports);
 __exportStar(require("./connect"), exports);
+__exportStar(require("./dashboard"), exports);
 __exportStar(require("./catalog"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./invoices"), exports);
@@ -33,5 +34,6 @@ __exportStar(require("./payments"), exports);
 __exportStar(require("./version"), exports);
 __exportStar(require("./checkout"), exports);
 __exportStar(require("./files"), exports);
+__exportStar(require("./identity"), exports);
 __exportStar(require("./merchants"), exports);
 __exportStar(require("./paymentMethodConfigurations"), exports);

package/dist/cjs/vocabulary/money.js

@@ -16,7 +16,7 @@ exports.isBaseUnitString = isBaseUnitString;
  * chain rail, and on the card rail the fiat set the provider settles for the
  * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
  * EPS). A local method narrows it further per payment
- * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfigurations.ts`).
  *
  * A closed set, and the database mirrors it as a CHECK
  * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property

package/dist/cjs/vocabulary/paymentMethodConfigurations.js

@@ -1,7 +1,8 @@
 "use strict";
 // Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
+exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
+const money_1 = require("./money");
 /**
  * The methods a configuration can turn on.
  *
@@ -34,3 +35,18 @@ exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',
     'requires_card',
 ];
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+exports.PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    card: money_1.FIAT_CURRENCY_CODES,
+    apple_pay: money_1.FIAT_CURRENCY_CODES,
+    google_pay: money_1.FIAT_CURRENCY_CODES,
+    sepa_debit: ['EUR'],
+    ideal: ['EUR'],
+    bancontact: ['EUR'],
+    eps: ['EUR'],
+    bizum: ['EUR'],
+});

package/dist/esm/vocabulary/dashboard.js

@@ -0,0 +1,64 @@
+// What a signed-in person may do in Orbit — the ONE map from a dashboard
+// action to the Oxy application permission it needs. Zod-free. The gateway
+// gates every `/v1/dashboard/applications/:id/*` and contribution route on it
+// (a refusal is `permission_required`, `param` naming the permission), and
+// Orbit hides or disables what the person lacks with the SAME map, so the two
+// can never disagree about who may do what.
+/**
+ * The permissions are oxy-api's own APPLICATION vocabulary
+ * (`packages/api/src/utils/accountRoles.ts`, `APPLICATION_PERMISSIONS`): Oxy
+ * resolves the person's role, grants and revokes on the account that owns the
+ * application into `callerMembership.permissions`, and that list — from
+ * `apps.get` on the gateway, from `apps.list` in Orbit — is the whole answer.
+ * Peable never reads a role name and keeps no membership copy.
+ */
+export const DASHBOARD_PERMISSIONS = {
+    /**
+     * Every read, the searches and a report run (it materialises the same rows a
+     * download streams). oxy-api answers an application only to a holder of
+     * `app:read`, so this is membership itself.
+     */
+    read: 'app:read',
+    /**
+     * The integration's configuration: branding and customer emails, the
+     * catalog, checkout sessions and payment links, contribution links, payment
+     * methods and wallet domains, a business logo.
+     */
+    configure: 'app:update',
+    /** Webhook endpoints and their signing secrets, test events, redelivery. */
+    webhooks: 'webhooks:update',
+    /**
+     * Money and who receives it: the merchant registration (its watch-only key
+     * and confirmations), the provider account and its onboarding and identity
+     * documents, payouts, sellers and transfers, disputes and their evidence, the
+     * billing engine, and every Peable Tax change or decision.
+     */
+    money: 'billing:manage',
+    /** Peable Tax reads and previews (ADR 0011, ADR 0020). */
+    taxRead: 'billing:read',
+};
+/**
+ * A permission that CONTAINS another: whoever may manage billing may read it.
+ * Stated once so the gateway and Orbit apply the same containment.
+ */
+const IMPLIED_BY = {
+    'billing:read': 'billing:manage',
+};
+/** Whether `held` (Oxy's `callerMembership.permissions`) allows `action`. */
+export function allowsDashboardAction(held, action) {
+    const required = DASHBOARD_PERMISSIONS[action];
+    const container = IMPLIED_BY[required];
+    return held.includes(required) || (container !== undefined && held.includes(container));
+}
+/**
+ * Uploading a file is the first half of USING it, so it needs what the use
+ * needs: a logo is configuration, everything else is evidence or identity for
+ * money (a dispute, the provider account, Peable Tax).
+ */
+export const FILE_UPLOAD_ACTION = {
+    business_logo: 'configure',
+    dispute_evidence: 'money',
+    identity_document: 'money',
+    additional_verification: 'money',
+    tax_document: 'money',
+};

package/dist/esm/vocabulary/errors.js

@@ -157,8 +157,9 @@ export const ERROR_CODE_DESCRIPTIONS = {
     // The dashboard routes (`/v1/dashboard/*`, Orbit): the signed-in person, not a credential.
     merchant_missing: 'The application has no merchant in this environment yet; register one (Orbit shows "Set up payments").',
     application_membership_required: 'The signed-in Oxy account is not a member of the account that owns this application.',
-    permission_required: 'The member lacks an Oxy permission this needs; `param` names it (`billing:read`, `billing:manage`). An owner grants it in Oxy Console.',
-    membership_unavailable: 'Oxy could not be asked whether the signed-in person is a member of this application; retry.',
+    account_membership_required: "The signed-in Oxy account is not a member of the Oxy account the path names (a contribution route's organization).",
+    permission_required: 'The member lacks the Oxy permission this action needs; `param` names it (`app:update`, `webhooks:update`, `billing:read`, `billing:manage`). An owner grants it in Oxy Console.',
+    membership_unavailable: 'Oxy could not be asked what the signed-in person may do on this application or account; retry.',
     session_invalid: 'Oxy no longer accepts the signed-in session; sign in again.',
 };
 /** Every error code, sorted. */

package/dist/esm/vocabulary/identity.js

@@ -0,0 +1,9 @@
+/**
+ * Peable's own Oxy application: the identity the gateway runs as (`OxyServer`'s
+ * `applicationId`) and the one an Oxy service addresses when it calls the
+ * gateway. One constant, so the gateway's accepted audience and the SDK's
+ * requested one cannot name two different applications.
+ */
+export const PEABLE_OXY_APPLICATION_ID = '6a2f851751b784a86fd0e958';
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+export const PEABLE_SERVICE_AUDIENCE = `oxy-service:${PEABLE_OXY_APPLICATION_ID}`;

package/dist/esm/vocabulary/index.js

@@ -4,6 +4,7 @@
 // package root, which constructs every schema at load.
 export * from './billingPortal.js';
 export * from './connect.js';
+export * from './dashboard.js';
 export * from './catalog.js';
 export * from './errors.js';
 export * from './invoices.js';
@@ -17,5 +18,6 @@ export * from './payments.js';
 export * from './version.js';
 export * from './checkout.js';
 export * from './files.js';
+export * from './identity.js';
 export * from './merchants.js';
 export * from './paymentMethodConfigurations.js';

package/dist/esm/vocabulary/money.js

@@ -10,7 +10,7 @@
  * chain rail, and on the card rail the fiat set the provider settles for the
  * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
  * EPS). A local method narrows it further per payment
- * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfigurations.ts`).
  *
  * A closed set, and the database mirrors it as a CHECK
  * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property

package/dist/esm/vocabulary/paymentMethodConfigurations.js

@@ -1,4 +1,5 @@
 // Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
+import { FIAT_CURRENCY_CODES } from './money.js';
 /**
  * The methods a configuration can turn on.
  *
@@ -31,3 +32,18 @@ export const PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',
     'requires_card',
 ];
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+export const PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    card: FIAT_CURRENCY_CODES,
+    apple_pay: FIAT_CURRENCY_CODES,
+    google_pay: FIAT_CURRENCY_CODES,
+    sepa_debit: ['EUR'],
+    ideal: ['EUR'],
+    bancontact: ['EUR'],
+    eps: ['EUR'],
+    bizum: ['EUR'],
+});

package/dist/types/vocabulary/dashboard.d.ts

@@ -0,0 +1,44 @@
+import type { FileUploadPurpose } from './files';
+/**
+ * The permissions are oxy-api's own APPLICATION vocabulary
+ * (`packages/api/src/utils/accountRoles.ts`, `APPLICATION_PERMISSIONS`): Oxy
+ * resolves the person's role, grants and revokes on the account that owns the
+ * application into `callerMembership.permissions`, and that list — from
+ * `apps.get` on the gateway, from `apps.list` in Orbit — is the whole answer.
+ * Peable never reads a role name and keeps no membership copy.
+ */
+export declare const DASHBOARD_PERMISSIONS: {
+    /**
+     * Every read, the searches and a report run (it materialises the same rows a
+     * download streams). oxy-api answers an application only to a holder of
+     * `app:read`, so this is membership itself.
+     */
+    readonly read: "app:read";
+    /**
+     * The integration's configuration: branding and customer emails, the
+     * catalog, checkout sessions and payment links, contribution links, payment
+     * methods and wallet domains, a business logo.
+     */
+    readonly configure: "app:update";
+    /** Webhook endpoints and their signing secrets, test events, redelivery. */
+    readonly webhooks: "webhooks:update";
+    /**
+     * Money and who receives it: the merchant registration (its watch-only key
+     * and confirmations), the provider account and its onboarding and identity
+     * documents, payouts, sellers and transfers, disputes and their evidence, the
+     * billing engine, and every Peable Tax change or decision.
+     */
+    readonly money: "billing:manage";
+    /** Peable Tax reads and previews (ADR 0011, ADR 0020). */
+    readonly taxRead: "billing:read";
+};
+export type DashboardAction = keyof typeof DASHBOARD_PERMISSIONS;
+export type DashboardPermission = (typeof DASHBOARD_PERMISSIONS)[DashboardAction];
+/** Whether `held` (Oxy's `callerMembership.permissions`) allows `action`. */
+export declare function allowsDashboardAction(held: readonly string[], action: DashboardAction): boolean;
+/**
+ * Uploading a file is the first half of USING it, so it needs what the use
+ * needs: a logo is configuration, everything else is evidence or identity for
+ * money (a dispute, the provider account, Peable Tax).
+ */
+export declare const FILE_UPLOAD_ACTION: Readonly<Record<FileUploadPurpose, DashboardAction>>;

package/dist/types/vocabulary/errors.d.ts

@@ -134,8 +134,9 @@ export declare const ERROR_CODE_DESCRIPTIONS: {
     readonly no_faircoin_half: "The connected account has no FairCoin half to register a key for.";
     readonly merchant_missing: "The application has no merchant in this environment yet; register one (Orbit shows \"Set up payments\").";
     readonly application_membership_required: "The signed-in Oxy account is not a member of the account that owns this application.";
-    readonly permission_required: "The member lacks an Oxy permission this needs; `param` names it (`billing:read`, `billing:manage`). An owner grants it in Oxy Console.";
-    readonly membership_unavailable: "Oxy could not be asked whether the signed-in person is a member of this application; retry.";
+    readonly account_membership_required: "The signed-in Oxy account is not a member of the Oxy account the path names (a contribution route's organization).";
+    readonly permission_required: "The member lacks the Oxy permission this action needs; `param` names it (`app:update`, `webhooks:update`, `billing:read`, `billing:manage`). An owner grants it in Oxy Console.";
+    readonly membership_unavailable: "Oxy could not be asked what the signed-in person may do on this application or account; retry.";
     readonly session_invalid: "Oxy no longer accepts the signed-in session; sign in again.";
 };
 export type ErrorCode = keyof typeof ERROR_CODE_DESCRIPTIONS;

package/dist/types/vocabulary/identity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Peable's own Oxy application: the identity the gateway runs as (`OxyServer`'s
+ * `applicationId`) and the one an Oxy service addresses when it calls the
+ * gateway. One constant, so the gateway's accepted audience and the SDK's
+ * requested one cannot name two different applications.
+ */
+export declare const PEABLE_OXY_APPLICATION_ID = "6a2f851751b784a86fd0e958";
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+export declare const PEABLE_SERVICE_AUDIENCE = "oxy-service:6a2f851751b784a86fd0e958";

package/dist/types/vocabulary/index.d.ts

@@ -1,5 +1,6 @@
 export * from './billingPortal';
 export * from './connect';
+export * from './dashboard';
 export * from './catalog';
 export * from './errors';
 export * from './invoices';
@@ -13,5 +14,6 @@ export * from './payments';
 export * from './version';
 export * from './checkout';
 export * from './files';
+export * from './identity';
 export * from './merchants';
 export * from './paymentMethodConfigurations';

package/dist/types/vocabulary/money.d.ts

@@ -3,7 +3,7 @@
  * chain rail, and on the card rail the fiat set the provider settles for the
  * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
  * EPS). A local method narrows it further per payment
- * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfigurations.ts`).
  *
  * A closed set, and the database mirrors it as a CHECK
  * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property

package/dist/types/vocabulary/paymentMethodConfigurations.d.ts

@@ -1,3 +1,4 @@
+import { type FiatCurrencyCode } from './money';
 /**
  * The methods a configuration can turn on.
  *
@@ -20,3 +21,9 @@ export type PaymentMethodConfigurationType = (typeof PAYMENT_METHOD_CONFIGURATIO
  */
 export declare const PAYMENT_METHOD_UNAVAILABLE_REASONS: readonly ["provider_unsupported", "requires_card"];
 export type PaymentMethodUnavailableReason = (typeof PAYMENT_METHOD_UNAVAILABLE_REASONS)[number];
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+export declare const PAYMENT_METHOD_CURRENCIES: Readonly<Record<PaymentMethodConfigurationType, readonly FiatCurrencyCode[]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/contracts",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The Peable wire, declared once: Zod contracts of every public route, the OpenAPI 3.1 generator and the closed value sets (ADR 0014 D5).",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -36,6 +36,18 @@
       },
       "default": "./dist/esm/vocabulary/index.js"
     },
+    "./vocabulary/*": {
+      "react-native": "./dist/esm/vocabulary/*.js",
+      "import": {
+        "types": "./dist/types/vocabulary/*.d.ts",
+        "default": "./dist/esm/vocabulary/*.js"
+      },
+      "require": {
+        "types": "./dist/types/vocabulary/*.d.ts",
+        "default": "./dist/cjs/vocabulary/*.js"
+      },
+      "default": "./dist/esm/vocabulary/*.js"
+    },
     "./contributions": {
       "react-native": "./dist/esm/contributions.js",
       "import": {
@@ -106,6 +118,9 @@
       "vocabulary": [
         "./dist/types/vocabulary/index.d.ts"
       ],
+      "vocabulary/*": [
+        "./dist/types/vocabulary/*.d.ts"
+      ],
       "contributions": [
         "./dist/types/contributions.d.ts"
       ],