@akira-io/billing-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# @akira-io/billing-js
+
+TypeScript client for the [Akira Billing API](https://github.com/akira-foundation/billing).
+Two surfaces:
+
+- **Storefront helpers** (`/pricing`, `/downloads`, `/checkout`, `/react`, `/vue`) — browser-safe,
+  no secret required. For landing pages, marketing sites, and SPAs that only call
+  unauthenticated endpoints.
+- **`BillingClient`** (`/client`) — full HMAC-signed client mirroring the
+  [Go](https://github.com/akira-io/billing-sdk-go) and
+  [Rust](https://github.com/akira-io/billing-sdk-rust) SDKs. For trusted runtimes that hold a
+  `productSecret`: Node servers, Next.js route handlers, Cloudflare Workers, Deno, Bun,
+  CLI scripts, controlled webviews. **Never ship the secret to a browser bundle.**
+
+Zero runtime dependencies. Dual ESM + CJS. Tree-shakeable per-module entry points.
+
+## BillingClient (`/client`)
+
+Runtime-agnostic class. Works anywhere `fetch` and `crypto.subtle` exist (Node 18+,
+Bun, Deno, Cloudflare Workers, every modern serverless runtime). Reads the secret
+from your environment, never from `import.meta.env` exposed to a browser bundle.
+
+### Serverless route handler — instantiate per request
+
+```ts
+import { BillingClient } from '@akira-io/billing-js/client';
+
+// app/api/login/route.ts (Next.js route handler — also fits Vercel, Netlify, CF Workers)
+export async function POST(req: Request) {
+    const client = new BillingClient({
+        baseUrl: process.env.AKIRA_BILLING_URL!,
+        productSlug: 'unified-dev',
+        productSecret: process.env.AKIRA_BILLING_SECRET!,
+    });
+    const { email, code } = await req.json();
+    const result = await client.verifyOtp({ email, code });
+    // store result.access_token in a session cookie
+    return Response.json(result);
+}
+```
+
+### Long-lived server — instantiate once, reuse
+
+```ts
+import { BillingClient } from '@akira-io/billing-js/client';
+import express from 'express';
+
+const billing = new BillingClient({
+    baseUrl: process.env.AKIRA_BILLING_URL!,
+    productSlug: 'unified-dev',
+    productSecret: process.env.AKIRA_BILLING_SECRET!,
+});
+
+const app = express();
+app.post('/login', async (req, res) => {
+    const result = await billing.verifyOtp(req.body);
+    res.json(result);
+});
+```
+
+### Per-customer token
+
+After OTP verify the SDK stores the bearer on the instance. For follow-up
+authenticated calls, either reuse the same client or call `setCustomerToken`:
+
+```ts
+client.setCustomerToken(req.cookies.akira_token);
+const me = await client.customerMe();
+const features = await client.entitlements();
+```
+
+### Available methods
+
+| Method | Endpoint |
+|---|---|
+| `requestOtp(payload)` | `POST /api/auth/customer/otp/request` |
+| `verifyOtp(payload)` | `POST /api/auth/customer/otp/verify` (auto-sets bearer) |
+| `customerMe()` | `GET /api/me` |
+| `licenseCheck(payload)` | `POST /api/licenses/check` |
+| `licenseActivate(payload)` | `POST /api/licenses/activate` |
+| `licenseRefresh(payload)` | `POST /api/licenses/refresh` |
+| `entitlements()` | `GET /api/me/entitlements` |
+| `billingPortal(returnUrl)` | `GET /api/billing/portal` |
+| `trackUsage(payload)` | `POST /api/me/usage` |
+| `publicLicenseKeys()` | `GET /api/v1/license-keys/public` (no HMAC) |
+
+### Errors
+
+Non-2xx responses throw `BillingApiError` with `status` and `code` fields populated
+from the server error payload.
+
+```ts
+import { BillingApiError } from '@akira-io/billing-js/client';
+
+try {
+    await client.licenseActivate({ ... });
+} catch (error) {
+    if (error instanceof BillingApiError && error.code === 'no_active_plan') {
+        // redirect to upgrade
+    }
+    throw error;
+}
+```
+
+### Custom fetch
+
+Pass `fetcher` to override `globalThis.fetch` (custom retry, observability, etc):
+
+```ts
+new BillingClient({ baseUrl, productSlug, productSecret, fetcher: myFetch });
+```
+
+
+## Install
+
+```bash
+pnpm add @akira-io/billing-js
+# or
+npm install @akira-io/billing-js
+```
+
+## Pricing
+
+```ts
+import { fetchPricing, formatPrice } from '@akira-io/billing-js/pricing';
+
+const pricing = await fetchPricing({
+    baseUrl: 'https://billing.akira.foundation',
+    productKey: 'unified-dev',
+    tierMeta: {
+        free: { tagline: 'Local dev', highlighted: false, label: 'Free', order: 10, ctaLabel: 'Download' },
+        pro:  { tagline: 'Unlimited runs', highlighted: true,  label: 'Pro',  order: 20, ctaLabel: 'Subscribe' },
+    },
+});
+
+pricing.tiers.forEach((tier) => {
+    const monthly = tier.monthly ? formatPrice(tier.monthly.amount, tier.monthly.currency) : '€0';
+    console.log(`${tier.name}: ${monthly}/month`);
+});
+```
+
+The shape of `PricingTier` mirrors what landing pages render: separate `monthly`, `yearly`,
+and `oneTime` slots with the originating `planKey` so you can build a checkout URL from it.
+
+## Downloads
+
+```ts
+import { triggerDownload } from '@akira-io/billing-js/downloads';
+
+document.querySelector('#download-arm')!.addEventListener('click', () =>
+    triggerDownload({
+        baseUrl: 'https://billing.akira.foundation',
+        product: 'unified-dev',
+        channel: 'stable',
+        platform: 'macos-arm64',
+        query: { utm_source: 'landing' },
+    }),
+);
+```
+
+`triggerDownload`:
+
+1. Calls `GET /api/v1/downloads/{product}/{channel}/{platform}` with `Accept: application/json`.
+2. Navigates the current tab to the returned signed URL.
+3. Schedules `navigator.sendBeacon` against the returned `beaconUrl` after a short delay so
+   the backend can mark the event as completed.
+
+Need more control? `issueDownload` returns the payload without redirecting; `downloadUrl`
+just builds the endpoint URL; `sendCompletionBeacon` ships the beacon on its own.
+
+## Checkout
+
+```ts
+import { checkoutUrl } from '@akira-io/billing-js/checkout';
+
+const url = checkoutUrl('https://billing.akira.foundation', 'unified-dev', 'pro_monthly');
+// → https://billing.akira.foundation/subscribe/unified-dev/pro_monthly
+```
+
+The billing app handles the rest (guest Stripe Checkout session, redirect, webhook).
+
+## React hooks (`/react`)
+
+```tsx
+import { usePricing, useDownload } from '@akira-io/billing-js/react';
+import { formatPrice } from '@akira-io/billing-js/pricing';
+
+function Pricing() {
+    const { data, isLoading, refresh } = usePricing({
+        baseUrl: 'https://billing.akira.foundation',
+        productKey: 'unified-dev',
+    });
+
+    if (isLoading) return <Skeleton />;
+
+    return data?.tiers.map((tier) => (
+        <Card key={tier.key}>
+            <h3>{tier.name}</h3>
+            {tier.monthly && <p>{formatPrice(tier.monthly.amount, tier.monthly.currency)}/mo</p>}
+            <ul>{tier.features.map((f) => <li key={f.key}>{f.name}</li>)}</ul>
+        </Card>
+    ));
+}
+
+function DownloadButton() {
+    const { trigger, isPending } = useDownload({
+        baseUrl: 'https://billing.akira.foundation',
+        product: 'unified-dev',
+        channel: 'stable',
+        platform: 'macos-arm64',
+    });
+    return <button disabled={isPending} onClick={trigger}>{isPending ? 'Starting…' : 'Download'}</button>;
+}
+```
+
+## Vue composables (`/vue`)
+
+```vue
+<script setup lang="ts">
+import { usePricing, useDownload } from '@akira-io/billing-js/vue';
+import { formatPrice } from '@akira-io/billing-js/pricing';
+
+const { data, isLoading } = usePricing(() => ({
+    baseUrl: 'https://billing.akira.foundation',
+    productKey: 'unified-dev',
+}));
+
+const { trigger, isPending } = useDownload(() => ({
+    baseUrl: 'https://billing.akira.foundation',
+    product: 'unified-dev',
+    channel: 'stable',
+    platform: 'macos-arm64',
+}));
+</script>
+
+<template>
+    <div v-if="isLoading">Loading…</div>
+    <div v-else v-for="tier in data?.tiers ?? []" :key="tier.key">
+        <h3>{{ tier.name }}</h3>
+        <p v-if="tier.monthly">{{ formatPrice(tier.monthly.amount, tier.monthly.currency) }}/mo</p>
+    </div>
+    <button :disabled="isPending" @click="trigger">{{ isPending ? 'Starting…' : 'Download' }}</button>
+</template>
+```
+
+React and Vue are listed as **optional peer dependencies** — install only the
+one your app needs. The core modules (`/pricing`, `/downloads`, `/checkout`)
+have no framework dependency.
+
+## Bundled types
+
+```ts
+import type {
+    PricingPayload,
+    PricingTier,
+    PricingFeature,
+    TierMeta,
+    IssuedDownload,
+    ReleaseChannel,
+    AssetPlatform,
+} from '@akira-io/billing-js';
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```
+
+## License
+
+MIT.

package/dist/checkout.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+// src/checkout.ts
+function checkoutUrl(baseUrl, productKey, planKey) {
+  return `${baseUrl.replace(/\/$/, "")}/subscribe/${productKey}/${planKey}`;
+}
+
+exports.checkoutUrl = checkoutUrl;
+//# sourceMappingURL=checkout.cjs.map
+//# sourceMappingURL=checkout.cjs.map

package/dist/checkout.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/checkout.ts"],"names":[],"mappings":";;;AAAO,SAAS,WAAA,CAAY,OAAA,EAAiB,UAAA,EAAoB,OAAA,EAAyB;AACtF,EAAA,OAAO,CAAA,EAAG,QAAQ,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAC,CAAA,WAAA,EAAc,UAAU,CAAA,CAAA,EAAI,OAAO,CAAA,CAAA;AAC3E","file":"checkout.cjs","sourcesContent":["export function checkoutUrl(baseUrl: string, productKey: string, planKey: string): string {\n    return `${baseUrl.replace(/\\/$/, '')}/subscribe/${productKey}/${planKey}`;\n}\n"]}

package/dist/checkout.d.cts

@@ -0,0 +1,3 @@
+declare function checkoutUrl(baseUrl: string, productKey: string, planKey: string): string;
+
+export { checkoutUrl };

package/dist/checkout.d.ts

@@ -0,0 +1,3 @@
+declare function checkoutUrl(baseUrl: string, productKey: string, planKey: string): string;
+
+export { checkoutUrl };

package/dist/checkout.js

@@ -0,0 +1,8 @@
+// src/checkout.ts
+function checkoutUrl(baseUrl, productKey, planKey) {
+  return `${baseUrl.replace(/\/$/, "")}/subscribe/${productKey}/${planKey}`;
+}
+
+export { checkoutUrl };
+//# sourceMappingURL=checkout.js.map
+//# sourceMappingURL=checkout.js.map

package/dist/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/checkout.ts"],"names":[],"mappings":";AAAO,SAAS,WAAA,CAAY,OAAA,EAAiB,UAAA,EAAoB,OAAA,EAAyB;AACtF,EAAA,OAAO,CAAA,EAAG,QAAQ,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAC,CAAA,WAAA,EAAc,UAAU,CAAA,CAAA,EAAI,OAAO,CAAA,CAAA;AAC3E","file":"checkout.js","sourcesContent":["export function checkoutUrl(baseUrl: string, productKey: string, planKey: string): string {\n    return `${baseUrl.replace(/\\/$/, '')}/subscribe/${productKey}/${planKey}`;\n}\n"]}

package/dist/client-DpOXhuxx.d.cts

@@ -0,0 +1,141 @@
+interface OtpRequestPayload {
+    email: string;
+    device_fp?: string;
+    platform?: string;
+    app_version?: string;
+}
+interface OtpVerifyPayload {
+    email: string;
+    code: string;
+    device_fp?: string;
+}
+interface OtpCustomer {
+    id: string;
+    email: string;
+}
+interface OtpVerifyResponse {
+    access_token: string;
+    customer: OtpCustomer;
+}
+interface Customer {
+    id: string;
+    email: string;
+    name: string | null;
+    trial_ends_at: string | null;
+    plan: string | null;
+}
+interface LicenseCheckPayload {
+    product: string;
+    feature: string;
+}
+interface LicenseCheckResponse {
+    allowed: boolean;
+    product: string;
+    plan: string | null;
+    feature: string;
+    source: string | null;
+}
+interface LicenseActivatePayload {
+    product: string;
+    device_type: string;
+    platform?: string;
+    device_name?: string;
+    app_version?: string;
+    fingerprint: string;
+}
+interface LicenseRefreshPayload {
+    product: string;
+    fingerprint: string;
+}
+interface SignedLicense {
+    key_id: string;
+    algorithm: string;
+    payload: string;
+    signature: string;
+    valid_until: string;
+}
+interface ActivatedDevice {
+    id: string;
+    type: string;
+    slots_used: number;
+    slots_limit: number | null;
+}
+interface LicenseActivateResponse {
+    allowed: boolean;
+    product: string;
+    plan: string;
+    features: Record<string, boolean>;
+    device: ActivatedDevice;
+    license: SignedLicense;
+}
+interface EntitlementCustomer {
+    id: string;
+    email: string;
+    name: string | null;
+}
+interface EntitlementsResponse {
+    customer: EntitlementCustomer;
+    entitlements: unknown;
+    devices: unknown;
+}
+interface BillingPortalResponse {
+    url: string;
+}
+interface LicensePublicKey {
+    key_id: string;
+    algorithm: string;
+    public_key_base64: string;
+}
+interface LicensePublicKeysResponse {
+    keys: LicensePublicKey[];
+    active_key_id: string | null;
+}
+interface UsagePayload {
+    product: string;
+    feature: string;
+    date: string;
+    device_fp: string;
+    action: 'check' | 'increment';
+}
+interface UsageResponse {
+    count: number;
+    limit: number | null;
+    allowed: boolean;
+}
+
+interface BillingClientConfig {
+    baseUrl: string;
+    productSlug: string;
+    productSecret: string;
+    customerToken?: string;
+    fetcher?: typeof fetch;
+}
+declare class BillingApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string);
+}
+declare class BillingClient {
+    private readonly baseUrl;
+    private readonly productSlug;
+    private readonly productSecret;
+    private customerToken;
+    private readonly fetcher;
+    constructor(config: BillingClientConfig);
+    setCustomerToken(token: string): void;
+    requestOtp(payload: OtpRequestPayload): Promise<void>;
+    verifyOtp(payload: OtpVerifyPayload): Promise<OtpVerifyResponse>;
+    customerMe(): Promise<Customer>;
+    licenseCheck(payload: LicenseCheckPayload): Promise<LicenseCheckResponse>;
+    licenseActivate(payload: LicenseActivatePayload): Promise<LicenseActivateResponse>;
+    licenseRefresh(payload: LicenseRefreshPayload): Promise<LicenseActivateResponse>;
+    entitlements(): Promise<EntitlementsResponse>;
+    billingPortal(returnUrl: string): Promise<BillingPortalResponse>;
+    trackUsage(payload: UsagePayload): Promise<UsageResponse>;
+    publicLicenseKeys(): Promise<LicensePublicKeysResponse>;
+    private signed;
+    private unsigned;
+    private parseResponse;
+}
+
+export { type ActivatedDevice as A, BillingApiError as B, type Customer as C, type EntitlementCustomer as E, type LicenseActivatePayload as L, type OtpCustomer as O, type SignedLicense as S, type UsagePayload as U, BillingClient as a, type BillingClientConfig as b, type BillingPortalResponse as c, type EntitlementsResponse as d, type LicenseActivateResponse as e, type LicenseCheckPayload as f, type LicenseCheckResponse as g, type LicensePublicKey as h, type LicensePublicKeysResponse as i, type LicenseRefreshPayload as j, type OtpRequestPayload as k, type OtpVerifyPayload as l, type OtpVerifyResponse as m, type UsageResponse as n };

package/dist/client-DpOXhuxx.d.ts

@@ -0,0 +1,141 @@
+interface OtpRequestPayload {
+    email: string;
+    device_fp?: string;
+    platform?: string;
+    app_version?: string;
+}
+interface OtpVerifyPayload {
+    email: string;
+    code: string;
+    device_fp?: string;
+}
+interface OtpCustomer {
+    id: string;
+    email: string;
+}
+interface OtpVerifyResponse {
+    access_token: string;
+    customer: OtpCustomer;
+}
+interface Customer {
+    id: string;
+    email: string;
+    name: string | null;
+    trial_ends_at: string | null;
+    plan: string | null;
+}
+interface LicenseCheckPayload {
+    product: string;
+    feature: string;
+}
+interface LicenseCheckResponse {
+    allowed: boolean;
+    product: string;
+    plan: string | null;
+    feature: string;
+    source: string | null;
+}
+interface LicenseActivatePayload {
+    product: string;
+    device_type: string;
+    platform?: string;
+    device_name?: string;
+    app_version?: string;
+    fingerprint: string;
+}
+interface LicenseRefreshPayload {
+    product: string;
+    fingerprint: string;
+}
+interface SignedLicense {
+    key_id: string;
+    algorithm: string;
+    payload: string;
+    signature: string;
+    valid_until: string;
+}
+interface ActivatedDevice {
+    id: string;
+    type: string;
+    slots_used: number;
+    slots_limit: number | null;
+}
+interface LicenseActivateResponse {
+    allowed: boolean;
+    product: string;
+    plan: string;
+    features: Record<string, boolean>;
+    device: ActivatedDevice;
+    license: SignedLicense;
+}
+interface EntitlementCustomer {
+    id: string;
+    email: string;
+    name: string | null;
+}
+interface EntitlementsResponse {
+    customer: EntitlementCustomer;
+    entitlements: unknown;
+    devices: unknown;
+}
+interface BillingPortalResponse {
+    url: string;
+}
+interface LicensePublicKey {
+    key_id: string;
+    algorithm: string;
+    public_key_base64: string;
+}
+interface LicensePublicKeysResponse {
+    keys: LicensePublicKey[];
+    active_key_id: string | null;
+}
+interface UsagePayload {
+    product: string;
+    feature: string;
+    date: string;
+    device_fp: string;
+    action: 'check' | 'increment';
+}
+interface UsageResponse {
+    count: number;
+    limit: number | null;
+    allowed: boolean;
+}
+
+interface BillingClientConfig {
+    baseUrl: string;
+    productSlug: string;
+    productSecret: string;
+    customerToken?: string;
+    fetcher?: typeof fetch;
+}
+declare class BillingApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string);
+}
+declare class BillingClient {
+    private readonly baseUrl;
+    private readonly productSlug;
+    private readonly productSecret;
+    private customerToken;
+    private readonly fetcher;
+    constructor(config: BillingClientConfig);
+    setCustomerToken(token: string): void;
+    requestOtp(payload: OtpRequestPayload): Promise<void>;
+    verifyOtp(payload: OtpVerifyPayload): Promise<OtpVerifyResponse>;
+    customerMe(): Promise<Customer>;
+    licenseCheck(payload: LicenseCheckPayload): Promise<LicenseCheckResponse>;
+    licenseActivate(payload: LicenseActivatePayload): Promise<LicenseActivateResponse>;
+    licenseRefresh(payload: LicenseRefreshPayload): Promise<LicenseActivateResponse>;
+    entitlements(): Promise<EntitlementsResponse>;
+    billingPortal(returnUrl: string): Promise<BillingPortalResponse>;
+    trackUsage(payload: UsagePayload): Promise<UsageResponse>;
+    publicLicenseKeys(): Promise<LicensePublicKeysResponse>;
+    private signed;
+    private unsigned;
+    private parseResponse;
+}
+
+export { type ActivatedDevice as A, BillingApiError as B, type Customer as C, type EntitlementCustomer as E, type LicenseActivatePayload as L, type OtpCustomer as O, type SignedLicense as S, type UsagePayload as U, BillingClient as a, type BillingClientConfig as b, type BillingPortalResponse as c, type EntitlementsResponse as d, type LicenseActivateResponse as e, type LicenseCheckPayload as f, type LicenseCheckResponse as g, type LicensePublicKey as h, type LicensePublicKeysResponse as i, type LicenseRefreshPayload as j, type OtpRequestPayload as k, type OtpVerifyPayload as l, type OtpVerifyResponse as m, type UsageResponse as n };