@abiyz/billing 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,99 @@
+ABIYZ BILLING SDK — TERMS OF USE
+
+Copyright (c) 2026 Abiyz Inc. All rights reserved.
+
+These terms govern your use of the Abiyz Billing software development kit,
+published on npm as @abiyz/billing (the "SDK"). By installing or using the
+SDK you agree to them. If you use it on behalf of an organization, you agree
+for that organization.
+
+1. What you may do
+
+   Abiyz Inc. ("Abiyz") grants you a non-exclusive, non-transferable,
+   royalty-free, revocable licence to install, use, copy and modify the SDK
+   for the sole purpose of building, testing and running applications that
+   use Abiyz Billing (your "applications"), and to distribute the SDK, as
+   modified by you or not, as part of your applications — including in the
+   code your applications send to your users' browsers and devices. Your
+   users need no licence from Abiyz to run what you send them.
+
+2. What you may not do
+
+   Except as these terms allow, or as applicable law permits despite them, you
+   may not:
+   (a) sell, rent, sublicense or distribute the SDK, or a modified version of
+       it, on its own or as part of a library, framework or development tool
+       for others to build with, rather than as part of your applications;
+   (b) remove or alter these terms or the copyright notice in the copies of
+       the SDK you distribute in source form;
+   (c) use the SDK with a billing service other than Abiyz Billing, use it
+       to access Abiyz Billing other than as your agreement for it allows, or
+       use it to interfere with the service; or
+   (d) use the SDK, or anything derived from it, to build a product that
+       competes with Abiyz Billing.
+
+3. The service is governed separately
+
+   The SDK is a client for Abiyz Billing. Your use of the service itself —
+   your account, your instances, your customers' data, what you are charged —
+   is governed by the terms of service that apply to your account, not by
+   these terms. If the two conflict about the service, those terms prevail.
+
+4. What the SDK does on the network
+
+   The SDK sends requests only to the Abiyz Billing address you name:
+   api.billing.abiyz.co, or the URL the console shows for your instance. It
+   sends them from your own server, with the instance key you give it, and
+   stores that key nowhere. The types it holds for the management API send
+   nothing. The SDK collects no usage data and sends nothing to Abiyz beyond
+   the requests you make with it.
+
+5. Third-party software
+
+   The SDK contains no third-party code and has no dependencies.
+
+6. Ownership
+
+   Abiyz and its licensors own the SDK and all rights in it, except those
+   granted to you here; you own your modifications, subject to these terms.
+   "Abiyz" and "Abiyz Billing", however capitalized, are names of Abiyz;
+   these terms grant no right to use them. Other names that appear in the SDK
+   or its documentation belong to their owners, and their appearance implies
+   no affiliation or endorsement.
+
+7. No warranty
+
+   THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTY OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, TO THE FULLEST
+   EXTENT PERMITTED BY LAW.
+
+8. Limitation of liability
+
+   TO THE FULLEST EXTENT PERMITTED BY LAW, ABIYZ WILL NOT BE LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR
+   ANY LOSS OF DATA, PROFITS OR REVENUE, ARISING FROM THE SDK OR YOUR USE OF
+   IT, AND ITS TOTAL LIABILITY ARISING FROM THE SDK WILL NOT EXCEED ONE
+   HUNDRED US DOLLARS (US$100). This section does not limit liability that
+   cannot be limited by law, and it does not affect anything the terms of
+   service for your account say about the service.
+
+9. Ending
+
+   These terms apply for as long as you use the SDK. They end automatically if
+   you breach them. When they end, stop using the SDK, delete your copies and
+   stop distributing it; copies already in the hands of your users under
+   section 1 may continue to be used by them. Sections 5 to 11 survive.
+
+10. Export
+
+   You will comply with the export control and sanctions laws that apply to
+   your use of the SDK, and you will not use it where those laws forbid.
+
+11. Law, changes and contact
+
+   These terms are governed by the laws of the State of Delaware, United
+   States, without regard to its conflict-of-laws rules. Each version of the
+   SDK comes with the terms that apply to it; a later version may come with
+   different terms. If any part of these terms is unenforceable, the rest
+   still applies. Questions: support@abiyz.com.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @abiyz/billing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Abiyz Billing for your application's server: sell credits, check a balance or a feature, charge
+before the work and settle after it.
+
+```sh
+npm install @abiyz/billing
+```
+
+ES modules, for Node 20 and later and for bundlers. The package has no dependencies. Its types use the
+standard `fetch` types, which `@types/node` or TypeScript's `DOM` library provides.
+
+## The runtime client
+
+Your application's server calls Billing with an instance key. Create the instance and its key in the
+console, at https://cloud.abiyz.com: the console shows the instance's URL and its key.
+A test key starts with `abiyz_cloud_bil_test_` and a live key with `abiyz_cloud_bil_live_`.
+
+Keep the key on your server, in its configuration and not in your source. Never ship it to a browser
+or a mobile application.
+
+```ts
+import { BillingError, createBillingRuntimeClient } from "@abiyz/billing";
+
+const billing = createBillingRuntimeClient({ key: "abiyz_cloud_bil_test_..." });
+```
+
+The client calls `https://api.billing.abiyz.co`. Pass `baseUrl` when the console shows another URL for your
+instance.
+
+Money is a decimal string in the instance's currency, with up to eight decimals. Every method that
+moves money takes an idempotency key that you choose: a retry with the same key answers the first
+result and charges nothing twice.
+
+### attach
+
+A checkout page where a customer buys a pack of credits. Redirect the customer to the URL.
+
+```ts
+const checkout = await billing.attach({ customer: "user_123", pack: "credits_10", rail: "stripe", successUrl: "https://example.com/thanks" });
+console.log(checkout.url);
+```
+
+### check
+
+Whether a charge would pass, or whether a customer's plan has a feature. It moves nothing.
+
+```ts
+const answer = await billing.check({ customer: "user_123", amount: "0.50" });
+if (!answer.allowed) console.log("not enough credit");
+```
+
+### track
+
+Charge after the work, with no hold.
+
+```ts
+const tracked = await billing.track({ customer: "user_123", meter: "tokens", quantity: 1200 }, { idempotencyKey: "job_42:track" });
+console.log(tracked.movements.length);
+```
+
+### hold
+
+Charge before the work: reserve an amount, so that the work never runs on credit the customer does
+not have.
+
+```ts
+const held = await billing.hold({ customer: "user_123", amount: "0.50", ttl: 600 }, { idempotencyKey: "job_43:hold" });
+const holdId = held.hold.id;
+```
+
+### settle
+
+Settle a hold after the work, for what the work cost.
+
+```ts
+await billing.settle(holdId, { amount: "0.42" }, { idempotencyKey: "job_43:settle" });
+```
+
+### release
+
+Release a hold and charge nothing, when the work did not happen.
+
+```ts
+await billing.release(holdId, { idempotencyKey: "job_43:release" });
+```
+
+### Errors
+
+An answer that is not a success throws `BillingError`, with the HTTP status and the problem Billing
+answered with.
+
+```ts
+try {
+  await billing.hold({ customer: "user_123", amount: "5000.00" }, { idempotencyKey: "job_44:hold" });
+} catch (error) {
+  if (error instanceof BillingError) console.log(error.status, error.problem?.code);
+  else throw error;
+}
+```
+
+The client does not retry. A retry is your decision, and with the same idempotency key it is safe.
+
+## The management client
+
+The management API creates and changes what the console does: instances, keys, packs, plans and
+policies. It answers at `https://api.abiyz.com/v1/billing` and takes a personal access token, which starts
+with `abiyz_cloud_pat_`, not an instance key. It never moves money.
+
+The package holds the management API's types, to use with `fetch` or with any typed client. The
+runtime API's types are beside them, as `BillingRuntimePaths`, `BillingRuntimeOperations` and
+`BillingRuntimeComponents`.
+
+```ts
+import type { BillingManagementOperations } from "@abiyz/billing";
+
+type InstanceList = BillingManagementOperations["listBillingInstances"]["responses"][200]["content"]["application/json"];
+
+const response = await fetch("https://api.abiyz.com/v1/billing/instances", { headers: { authorization: "Bearer abiyz_cloud_pat_..." } });
+const instances = (await response.json()) as InstanceList;
+console.log(instances);
+```