@bify/sdk 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 BIFY
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,123 @@
+# BIFY Server SDK
+
+`@bify/sdk` is the trusted integration package for partner-owned commerce. A
+partner keeps its own catalogue, prices, inventory, cart, checkout, and
+fulfilment systems. BIFY receives an immutable order snapshot and provides
+settlement, on-chain purchase records, certificates, rewards, and customer
+access infrastructure.
+
+```bash
+npm install @bify/sdk
+```
+
+```ts
+import { BifyClient } from "@bify/sdk";
+
+const bify = new BifyClient({ apiKey: process.env.BIFY_API_KEY });
+```
+
+The API key is a server-side credential. It must never reach the browser.
+
+## Checkout
+
+```ts
+const session = await bify.checkout.createOrderSession({
+  externalProductId: order.lineItem.externalProductId,
+  productName: order.lineItem.name,
+  productCategory: order.lineItem.category,
+  totalPriceUsdc: order.totalUsdcBaseUnits,
+  quantity: order.quantity,
+  externalOrderId: order.id,
+  shippingRequired: true,
+  idempotencyKey: `checkout:${order.id}`,
+  // Customer details are optional here; the BIFY widget can collect them.
+});
+```
+
+Read the price from your own catalogue on the server, never from the request
+body — otherwise a tampered client can mint a cheap session.
+
+Pass only `session.id` and `session.clientToken` to the browser. The widget
+takes it from there.
+
+## Settlement rails
+
+A session is always **denominated in USDC**. Which rail settles it is the
+buyer's choice, made in the widget from `session.paymentMethods`:
+
+- **`usdc`** — the buyer connects a wallet, approves USDC to the payment
+  router, and submits the contract-backed `payHostedOrder` transaction.
+- **`card`** — the buyer pays with a card through the payment processor. The
+  charge settles off-chain and is recorded on-chain with no value transfer, so
+  a buyer with no funded wallet can still complete a purchase and receive a
+  certificate.
+
+`paymentMethods` contains `card` only when the deployment has a payment
+processor configured; the backend omits it otherwise, so the widget never
+offers a rail that cannot settle.
+
+`createOrderSession` therefore accepts no rail selection — passing
+`paymentMethod: "card"` is rejected. There is nothing for a partner server to
+choose: the order total is the same either way.
+
+After settlement, on either rail, the widget fetches a signed certificate
+voucher, the buyer submits `mintCertificate` from their own wallet, and the
+widget confirms that mint with the backend.
+
+## Webhooks
+
+Events are signed with HMAC-SHA256 over `{timestamp}.{raw body}` and delivered
+in the `BIFY-Signature` header as `t=<unix>,v1=<hex>`.
+
+```ts
+import { parseVerifiedWebhook } from "@bify/sdk";
+
+const event = parseVerifiedWebhook({
+  payload: rawRequestBody,          // the untouched bytes, not a re-serialized object
+  signature: req.headers["bify-signature"],
+  secret: process.env.BIFY_WEBHOOK_SECRET,
+});
+```
+
+Verify against the **raw** body. Parsing and re-serializing JSON first changes
+the bytes and invalidates the signature.
+
+`secret` also accepts an array, so a rotation can be performed with no downtime
+by accepting the previous and current secrets during the overlap window.
+
+Event names are typed as `BifyEventName`.
+
+## What the SDK covers
+
+- hosted order sessions and status retrieval;
+- signed certificate voucher retrieval and on-chain mint confirmation;
+- partner-scoped order, fulfilment, certificate, reward, access, voting, and
+  identity APIs;
+- idempotency keys, timeout handling, typed errors, and webhook verification.
+
+The SDK does not submit wallet transactions. Use
+`checkout.getCertificateVoucher()` when a partner server needs to coordinate a
+custom browser experience; the browser widget or a voucher widget must submit
+the buyer-signed certificate mint.
+
+## Boundaries
+
+BIFY does not provide product registration, inventory, price authority, quote
+calculation, marketplace/resale, or managed wallets. Those decisions remain
+with the partner. RWA flows remain in the separate RWA frontend/backend.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+The browser widget is published as
+[`@bify/commerce-widget`](https://www.npmjs.com/package/@bify/commerce-widget).
+Canonical documentation is maintained in GitBook.
+
+## Licence
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { BifyClientOptions, BifyCapabilities, BifyEvent, CampaignStatus, CreateCampaignInput, CertificateListInput, CertificatePage, CertificateStatus, CertificateMintConfirmation, CheckoutCertificateVoucher, CheckoutSession, CheckoutSessionStatus, ClaimStatus, ConfirmRewardClaimInput, CreateOrderCheckoutSessionInput, GetCertificateVoucherInput, ConfirmCertificateMintInput, FulfilmentInput, OrderLookup, OrderStatus, RewardClaimInput, VerifyWebhookInput, AccessPassStatus, AccessGrantStatus, CreateAccessPassInput, CreatePollInput, IdentityAttestationInput, IdentityAttestationResult, PollStatus } from "./types.js";
+export declare class BifyClient {
+    private readonly http;
+    readonly checkout: {
+        createOrderSession: (input: CreateOrderCheckoutSessionInput) => Promise<CheckoutSession>;
+        retrieve: (sessionId: string) => Promise<CheckoutSessionStatus>;
+        getCertificateVoucher: (input: GetCertificateVoucherInput) => Promise<CheckoutCertificateVoucher>;
+    };
+    readonly capabilities: {
+        /**
+         * Deployment-level capability report. Describes the deployment as a whole;
+         * the rails available for a specific order come from
+         * `CheckoutSession.paymentMethods`, which is resolved per session.
+         */
+        retrieve: () => Promise<BifyCapabilities>;
+    };
+    readonly orders: {
+        retrieve: (input: OrderLookup) => Promise<OrderStatus>;
+        markFulfilled: (input: FulfilmentInput) => Promise<OrderStatus>;
+    };
+    readonly certificates: {
+        retrieve: (certificateId: string) => Promise<CertificateStatus>;
+        verify: (certificateId: string) => Promise<CertificateStatus>;
+        list: (input?: CertificateListInput) => Promise<CertificatePage>;
+        confirmMint: (input: ConfirmCertificateMintInput) => Promise<CertificateMintConfirmation>;
+    };
+    readonly rewards: {
+        create: (input: CreateCampaignInput) => Promise<CampaignStatus>;
+        retrieve: (campaignId: string) => Promise<CampaignStatus>;
+        claim: (input: RewardClaimInput) => Promise<ClaimStatus>;
+        confirmClaim: (input: ConfirmRewardClaimInput) => Promise<ClaimStatus>;
+        retrieveClaim: (claimId: string) => Promise<ClaimStatus>;
+    };
+    readonly access: {
+        create: (input: CreateAccessPassInput) => Promise<AccessPassStatus>;
+        retrieve: (accessId: string) => Promise<AccessPassStatus>;
+        setActive: (accessId: string, active: boolean) => Promise<AccessPassStatus>;
+        grant: (accessId: string, walletAddress: `0x${string}`) => Promise<AccessGrantStatus>;
+        revoke: (accessId: string, walletAddress: `0x${string}`) => Promise<AccessGrantStatus>;
+    };
+    readonly voting: {
+        createPoll: (input: CreatePollInput) => Promise<PollStatus>;
+        retrievePoll: (pollId: string) => Promise<PollStatus>;
+        setPollActive: (pollId: string, active: boolean) => Promise<PollStatus>;
+    };
+    readonly identity: {
+        attest: (input: IdentityAttestationInput) => Promise<IdentityAttestationResult>;
+    };
+    readonly webhooks: {
+        verify: <T = Record<string, unknown>>(input: VerifyWebhookInput) => BifyEvent<T>;
+    };
+    constructor(options: BifyClientOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,uBAAuB,EACvB,+BAA+B,EAC/B,0BAA0B,EAC1B,2BAA2B,EAC3B,eAAe,EACf,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,UAAU,EACX,MAAM,YAAY,CAAC;AA2EpB,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IAEtC,QAAQ,CAAC,QAAQ;oCACa,+BAA+B;8BAQrC,MAAM;uCACG,0BAA0B;MAQzD;IAEF,QAAQ,CAAC,YAAY;QACnB;;;;WAIG;;MAEH;IAEF,QAAQ,CAAC,MAAM;0BACK,WAAW;+BAQN,eAAe;MAWtC;IAEF,QAAQ,CAAC,YAAY;kCACO,MAAM;gCACR,MAAM;uBAChB,oBAAoB;6BAYb,2BAA2B;MAchD;IAEF,QAAQ,CAAC,OAAO;wBACE,mBAAmB;+BAKZ,MAAM;uBACd,gBAAgB;8BAQT,uBAAuB;iCAYpB,MAAM;MAC/B;IAEF,QAAQ,CAAC,MAAM;wBACG,qBAAqB;6BAKhB,MAAM;8BACL,MAAM,UAAU,OAAO;0BAK3B,MAAM,iBAAiB,KAAK,MAAM,EAAE;2BAKnC,MAAM,iBAAiB,KAAK,MAAM,EAAE;MAKvD;IAEF,QAAQ,CAAC,MAAM;4BACO,eAAe;+BAKZ,MAAM;gCACL,MAAM,UAAU,OAAO;MAK/C;IAEF,QAAQ,CAAC,QAAQ;wBACC,wBAAwB;MAexC;IAEF,QAAQ,CAAC,QAAQ;iBACN,CAAC,mCAAmC,kBAAkB,KAAG,SAAS,CAAC,CAAC,CAAC;MAC9E;gBAEU,OAAO,EAAE,iBAAiB;CAKvC"}

package/dist/client.js

@@ -0,0 +1,256 @@
+import { BifyHttpClient } from "./http.js";
+import { parseVerifiedWebhook } from "./webhooks.js";
+import { BifyValidationError } from "./errors.js";
+function validateIdentifier(value, label, maxLength = 255) {
+    if (typeof value !== "string" || !value.trim())
+        throw new BifyValidationError(`${label} is required.`);
+    const normalized = value.trim();
+    if (normalized.length > maxLength)
+        throw new BifyValidationError(`${label} must be ${maxLength} characters or fewer.`);
+    return normalized;
+}
+function validateQuantity(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new BifyValidationError("Quantity must be a positive safe integer.");
+    return value;
+}
+function validateIdempotencyKey(value) {
+    const key = validateIdentifier(value, "Idempotency key");
+    if (key.length > 255)
+        throw new BifyValidationError("Idempotency key must be 255 characters or fewer.");
+    return key;
+}
+function validateCustomer(customer) {
+    if (!customer || typeof customer !== "object")
+        throw new BifyValidationError("Customer details are required.");
+    if (typeof customer.name !== "string" || !customer.name.trim() || customer.name.trim().length > 200)
+        throw new BifyValidationError("Customer name is required and must be 200 characters or fewer.");
+    if (typeof customer.email !== "string" || !customer.email.trim() || customer.email.trim().length > 320 || !/^\S+@\S+\.\S+$/.test(customer.email.trim()))
+        throw new BifyValidationError("A valid customer email is required.");
+    if (customer.phone !== undefined && (typeof customer.phone !== "string" || customer.phone.trim().length > 32))
+        throw new BifyValidationError("Customer phone number is invalid.");
+    for (const [label, address] of [["shipping address", customer.shippingAddress], ["billing address", customer.billingAddress]]) {
+        if (!address)
+            continue;
+        if (typeof address !== "object" || typeof address.line1 !== "string" || (address.line2 !== undefined && typeof address.line2 !== "string") || typeof address.city !== "string" || typeof address.region !== "string" || typeof address.postalCode !== "string" || typeof address.country !== "string" || !address.line1.trim() || address.line1.trim().length > 200 || (typeof address.line2 === "string" && address.line2.trim().length > 200) || !address.city.trim() || address.city.trim().length > 100 || !address.region.trim() || address.region.trim().length > 100 || !address.postalCode.trim() || address.postalCode.trim().length > 32 || !/^[A-Za-z]{2}$/.test(address.country.trim()))
+            throw new BifyValidationError(`${label} is incomplete.`);
+    }
+    if (customer.billingSameAsShipping && !customer.shippingAddress)
+        throw new BifyValidationError("Shipping address is required when billing uses the same address.");
+    return customer;
+}
+function validateWalletAddress(value, label) {
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) {
+        throw new BifyValidationError(`${label} must be a valid EVM wallet address.`);
+    }
+    return value;
+}
+function externalOrderSessionInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new BifyValidationError("Checkout session input is required.");
+    const paymentMethod = input.paymentMethod ?? "usdc";
+    // A checkout session is always denominated in USDC. The settlement rail is
+    // selected by the buyer in the widget from `session.paymentMethods`, which the
+    // backend populates with the rails a deployment can actually settle, so a
+    // partner server has no rail to choose at creation time.
+    if (paymentMethod !== "usdc") {
+        throw new BifyValidationError("Checkout sessions are always created in USDC. The buyer picks the settlement rail in the widget from session.paymentMethods, which includes 'card' when the deployment has a payment processor configured.");
+    }
+    const checkoutMode = "hosted_transfer";
+    const externalProductId = validateIdentifier(input.externalProductId, "External product ID");
+    const productName = validateIdentifier(input.productName, "Product name");
+    const productCategory = validateIdentifier(input.productCategory, "Product category");
+    const unitPriceUsdc = input.unitPriceUsdc === undefined ? undefined : validateIdentifier(input.unitPriceUsdc, "Unit USDC amount");
+    if (unitPriceUsdc !== undefined && (!/^[0-9]+$/.test(unitPriceUsdc) || BigInt(unitPriceUsdc) <= 0n))
+        throw new BifyValidationError("Unit USDC amount must be a positive integer in base units.");
+    const totalPriceUsdc = validateIdentifier(input.totalPriceUsdc, "Total USDC amount");
+    if (!/^[0-9]+$/.test(totalPriceUsdc) || BigInt(totalPriceUsdc) <= 0n)
+        throw new BifyValidationError("Total USDC amount must be a positive integer in base units.");
+    return {
+        externalProductId, productName, productCategory, unitPriceUsdc, totalPriceUsdc,
+        shippingRequired: input.shippingRequired ?? false,
+        quantity: validateQuantity(input.quantity),
+        externalOrderId: validateIdentifier(input.externalOrderId, "External order ID"),
+        // The session is created denominated in USDC. Which rail the buyer actually uses is chosen in the
+        // widget from the rails the deployment can settle (session.paymentMethods), so a card buyer needs no
+        // change here — the order total is the same either way.
+        paymentMethod: "usdc", checkoutMode, certificate: input.certificate,
+        customer: input.customer ? validateCustomer(input.customer) : undefined, idempotencyKey: validateIdempotencyKey(input.idempotencyKey),
+        walletAddress: input.walletAddress === undefined ? undefined : validateWalletAddress(input.walletAddress, "Wallet address"),
+    };
+}
+export class BifyClient {
+    http;
+    checkout = {
+        createOrderSession: (input) => {
+            const body = externalOrderSessionInput(input);
+            return this.http.request("/v1/checkout/sessions", {
+                method: "POST",
+                body,
+                idempotencyKey: body.idempotencyKey,
+            });
+        },
+        retrieve: (sessionId) => this.http.request(`/v1/checkout/sessions/${encodeURIComponent(validateIdentifier(sessionId, "Session ID"))}`),
+        getCertificateVoucher: (input) => {
+            if (!input || typeof input !== "object")
+                throw new BifyValidationError("Certificate voucher input is required.");
+            const sessionId = validateIdentifier(input.sessionId, "Session ID");
+            const clientToken = validateIdentifier(input.clientToken, "Checkout client token");
+            return this.http.request(`/v1/public/checkout/sessions/${encodeURIComponent(sessionId)}/certificate/voucher`, {
+                method: "POST", body: { clientToken }, auth: false,
+            });
+        },
+    };
+    capabilities = {
+        /**
+         * Deployment-level capability report. Describes the deployment as a whole;
+         * the rails available for a specific order come from
+         * `CheckoutSession.paymentMethods`, which is resolved per session.
+         */
+        retrieve: () => this.http.request("/v1/capabilities", { auth: false }),
+    };
+    orders = {
+        retrieve: (input) => {
+            const value = input.orderId?.trim() || input.externalOrderId?.trim();
+            if (!value)
+                throw new BifyValidationError("Order ID or external order ID is required.");
+            const query = input.orderId?.trim()
+                ? `orderId=${encodeURIComponent(input.orderId.trim())}`
+                : `externalOrderId=${encodeURIComponent(input.externalOrderId.trim())}`;
+            return this.http.request(`/v1/orders?${query}`);
+        },
+        markFulfilled: (input) => this.http.request(`/v1/orders/${encodeURIComponent(validateIdentifier(input.orderId, "Order ID"))}/fulfilment`, {
+            method: "POST",
+            body: {
+                fulfilledAt: input.fulfilledAt,
+                fulfilmentReference: input.fulfilmentReference,
+            },
+            idempotencyKey: validateIdempotencyKey(input.idempotencyKey),
+        }),
+    };
+    certificates = {
+        retrieve: (certificateId) => this.http.request(`/v1/certificates/${encodeURIComponent(validateIdentifier(certificateId, "Certificate ID"))}`),
+        verify: (certificateId) => this.http.request(`/v1/public/certificates/${encodeURIComponent(validateIdentifier(certificateId, "Certificate ID"))}`, { auth: false }),
+        list: (input = {}) => {
+            const query = new URLSearchParams();
+            if (input.status)
+                query.set("status", input.status);
+            if (input.limit !== undefined) {
+                if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 100) {
+                    throw new BifyValidationError("Certificate page size must be between 1 and 100.");
+                }
+                query.set("limit", String(input.limit));
+            }
+            if (input.cursor)
+                query.set("cursor", input.cursor);
+            return this.http.request(`/v1/certificates${query.size ? `?${query}` : ""}`);
+        },
+        confirmMint: (input) => {
+            if (!input || typeof input !== "object")
+                throw new BifyValidationError("Certificate confirmation input is required.");
+            const sessionId = validateIdentifier(input.sessionId, "Session ID");
+            const token = validateIdentifier(input.clientToken, "Checkout client token");
+            const certificateId = validateIdentifier(input.certificateId, "Certificate ID");
+            if (!/^0x[0-9a-fA-F]{64}$/.test(certificateId) || !/^0x[0-9a-fA-F]{64}$/.test(input.transactionHash)) {
+                throw new BifyValidationError("Certificate ID and transaction hash must be 32-byte hex values.");
+            }
+            return this.http.request(`/v1/public/checkout/sessions/${encodeURIComponent(sessionId)}/certificate/confirm`, {
+                method: "POST",
+                body: { clientToken: token, certificateId, transactionHash: input.transactionHash },
+                auth: false,
+            });
+        },
+    };
+    rewards = {
+        create: (input) => this.http.request("/v1/rewards/campaigns", {
+            method: "POST",
+            body: { ...input },
+            idempotencyKey: input.id ?? `campaign:${input.rewardType}`,
+        }),
+        retrieve: (campaignId) => this.http.request(`/v1/rewards/campaigns/${encodeURIComponent(validateIdentifier(campaignId, "Campaign ID"))}`),
+        claim: (input) => this.http.request(`/v1/rewards/campaigns/${encodeURIComponent(validateIdentifier(input.campaignId, "Campaign ID"))}/claims`, {
+            method: "POST",
+            body: { purchaseId: input.purchaseId, claimant: input.claimant },
+            idempotencyKey: validateIdempotencyKey(input.idempotencyKey),
+        }),
+        confirmClaim: (input) => {
+            if (!input || typeof input !== "object")
+                throw new BifyValidationError("Reward confirmation input is required.");
+            const claimId = validateIdentifier(input.claimId, "Claim ID");
+            if (!/^0x[0-9a-fA-F]{64}$/.test(claimId) || !/^0x[0-9a-fA-F]{64}$/.test(input.transactionHash)) {
+                throw new BifyValidationError("Claim ID and transaction hash must be 32-byte hex values.");
+            }
+            return this.http.request(`/v1/public/rewards/claims/${encodeURIComponent(claimId)}/confirm`, {
+                method: "POST",
+                body: { transactionHash: input.transactionHash },
+                auth: false,
+            });
+        },
+        retrieveClaim: (claimId) => this.http.request(`/v1/rewards/claims/${encodeURIComponent(validateIdentifier(claimId, "Claim ID"))}`),
+    };
+    access = {
+        create: (input) => this.http.request("/v1/access-passes", {
+            method: "POST",
+            body: input,
+            idempotencyKey: input.accessId,
+        }),
+        retrieve: (accessId) => this.http.request(`/v1/access-passes/${encodeURIComponent(validateIdentifier(accessId, "Access pass ID"))}`),
+        setActive: (accessId, active) => this.http.request(`/v1/access-passes/${encodeURIComponent(validateIdentifier(accessId, "Access pass ID"))}/status`, {
+            method: "POST",
+            body: { active },
+            idempotencyKey: `access-status:${accessId}:${active ? "active" : "paused"}`,
+        }),
+        grant: (accessId, walletAddress) => this.http.request(`/v1/access-passes/${encodeURIComponent(validateIdentifier(accessId, "Access pass ID"))}/grants`, {
+            method: "POST",
+            body: { walletAddress },
+            idempotencyKey: `access-grant:${accessId}:${walletAddress.toLowerCase()}`,
+        }),
+        revoke: (accessId, walletAddress) => this.http.request(`/v1/access-passes/${encodeURIComponent(validateIdentifier(accessId, "Access pass ID"))}/revoke`, {
+            method: "POST",
+            body: { walletAddress },
+            idempotencyKey: `access-revoke:${accessId}:${walletAddress.toLowerCase()}`,
+        }),
+    };
+    voting = {
+        createPoll: (input) => this.http.request("/v1/voting/polls", {
+            method: "POST",
+            body: input,
+            idempotencyKey: input.pollId,
+        }),
+        retrievePoll: (pollId) => this.http.request(`/v1/voting/polls/${encodeURIComponent(validateIdentifier(pollId, "Poll ID"))}`),
+        setPollActive: (pollId, active) => this.http.request(`/v1/voting/polls/${encodeURIComponent(validateIdentifier(pollId, "Poll ID"))}/status`, {
+            method: "POST",
+            body: { active },
+            idempotencyKey: `poll-status:${pollId}:${active ? "active" : "paused"}`,
+        }),
+    };
+    identity = {
+        attest: (input) => {
+            const signature = validateIdentifier(input.signature, "Identity attestation signature");
+            if (!/^t=\d+,v1=[0-9a-fA-F]{64}$/.test(signature)) {
+                throw new BifyValidationError("Identity attestation signature is invalid.");
+            }
+            if (!Number.isSafeInteger(input.occurredAt) || input.occurredAt < 1)
+                throw new BifyValidationError("Identity event time is invalid.");
+            if (!Number.isSafeInteger(input.kycExpiresAt) || input.kycExpiresAt < 0)
+                throw new BifyValidationError("Identity expiry is invalid.");
+            if (!Number.isInteger(input.kycStatus) || input.kycStatus < 0 || input.kycStatus > 5)
+                throw new BifyValidationError("KYC status is invalid.");
+            return this.http.request("/v1/identity/attest", {
+                method: "POST",
+                auth: false,
+                body: { ...input, signature: undefined },
+                headers: { "BIFY-KYC-Signature": signature },
+            });
+        },
+    };
+    webhooks = {
+        verify: (input) => parseVerifiedWebhook(input),
+    };
+    constructor(options) {
+        // @dev: This client is intended for partner backend code. Browser code
+        // should use the public widget/session-token flow instead of this client.
+        this.http = new BifyHttpClient(options);
+    }
+}
+//# sourceMappingURL=client.js.map