@hanzo/iam 0.1.0 → 0.3.0

package/src/billing.ts

@@ -1,72 +1,118 @@
 /**
- * Billing client for Hanzo IAM (Casdoor) — subscriptions, plans, pricing, usage.
+ * @hanzo/iam/billing — Billing client for Hanzo Commerce API.
+ *
+ * Canonical billing lives in commerce.js/billing. This provides the same
+ * client for convenience when @hanzo/iam is already installed.
+ * Both talk to Commerce API — one way to do billing.
+ *
+ * @example
+ * ```ts
+ * // Preferred:
+ * import { BillingClient } from 'commerce.js/billing'
+ *
+ * // Also works:
+ * import { BillingClient } from '@hanzo/iam/billing'
+ * ```
  */
 
-import type {
-  IamConfig,
-  IamSubscription,
-  IamPlan,
-  IamPricing,
-  IamPayment,
-  IamOrder,
-  IamApiResponse,
-} from "./types.js";
-
 const DEFAULT_TIMEOUT_MS = 10_000;
 
-export class IamBillingClient {
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export type CommerceConfig = {
+  /** Commerce API base URL (e.g. "https://commerce.hanzo.ai"). */
+  commerceUrl: string;
+  /** Optional IAM access token for authenticated requests. */
+  token?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Balance = {
+  balance: number;
+  holds: number;
+  available: number;
+};
+
+export type Transaction = {
+  id?: string;
+  type: "hold" | "hold-removed" | "transfer" | "deposit" | "withdraw";
+  currency: string;
+  amount: number;
+  tags?: string[];
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+  createdAt?: string;
+};
+
+export type Subscription = {
+  id?: string;
+  planId?: string;
+  userId?: string;
+  status?: string;
+  billingType?: string;
+  periodStart?: string;
+  periodEnd?: string;
+  createdAt?: string;
+};
+
+export type Plan = {
+  slug?: string;
+  name?: string;
+  description?: string;
+  price?: number;
+  currency?: string;
+  interval?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type Payment = {
+  id?: string;
+  orderId?: string;
+  amount?: number;
+  currency?: string;
+  status?: string;
+  captured?: boolean;
+  createdAt?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+export class BillingClient {
   private readonly baseUrl: string;
-  private readonly clientId: string;
-  private readonly clientSecret: string | undefined;
-  private readonly orgName: string | undefined;
+  private token: string | undefined;
 
-  constructor(config: IamConfig) {
-    this.baseUrl = config.serverUrl.replace(/\/+$/, "");
-    this.clientId = config.clientId;
-    this.clientSecret = config.clientSecret;
-    this.orgName = config.orgName;
+  constructor(config: CommerceConfig) {
+    this.baseUrl = config.commerceUrl.replace(/\/+$/, "");
+    this.token = config.token;
   }
 
-  // -----------------------------------------------------------------------
-  // Internal HTTP helper
-  // -----------------------------------------------------------------------
+  setToken(token: string) {
+    this.token = token;
+  }
 
   private async request<T>(
     path: string,
-    opts?: {
-      method?: string;
-      body?: unknown;
-      token?: string;
-      params?: Record<string, string>;
-    },
+    opts?: { method?: string; body?: unknown; token?: string; params?: Record<string, string> },
   ): Promise<T> {
     const url = new URL(path, this.baseUrl);
     if (opts?.params) {
-      for (const [k, v] of Object.entries(opts.params)) {
-        url.searchParams.set(k, v);
-      }
+      for (const [k, v] of Object.entries(opts.params)) url.searchParams.set(k, v);
     }
 
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
 
-    const headers: Record<string, string> = {
-      Accept: "application/json",
-    };
-    if (opts?.token) {
-      headers.Authorization = `Bearer ${opts.token}`;
-    }
-    if (opts?.body) {
-      headers["Content-Type"] = "application/json";
-    }
-    if (this.clientSecret && !opts?.token) {
-      const credentials = `${this.clientId}:${this.clientSecret}`;
-      const basic =
-        typeof Buffer !== "undefined"
-          ? Buffer.from(credentials).toString("base64")
-          : btoa(credentials);
-      headers.Authorization = `Basic ${basic}`;
-    }
+    const headers: Record<string, string> = { Accept: "application/json" };
+    const authToken = opts?.token ?? this.token;
+    if (authToken) headers.Authorization = `Bearer ${authToken}`;
+    if (opts?.body) headers["Content-Type"] = "application/json";
 
     try {
       const res = await fetch(url.toString(), {
@@ -75,164 +121,85 @@ export class IamBillingClient {
         body: opts?.body ? JSON.stringify(opts.body) : undefined,
         signal: controller.signal,
       });
-
       if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(`IAM billing request failed (${res.status}): ${text}`.trim());
+        throw new CommerceApiError(res.status, `${res.statusText}: ${text}`.trim());
       }
-
       return (await res.json()) as T;
     } finally {
       clearTimeout(timer);
     }
   }
 
-  // -----------------------------------------------------------------------
-  // Subscriptions
-  // -----------------------------------------------------------------------
-
-  /** Get all subscriptions for an owner. */
-  async getSubscriptions(token?: string): Promise<IamSubscription[]> {
-    const owner = this.orgName ?? "admin";
-    const resp = await this.request<IamApiResponse<IamSubscription[]>>(
-      "/api/get-subscriptions",
-      { params: { owner }, token },
-    );
-    return resp.data ?? [];
-  }
-
-  /** Get a specific subscription by ID ("owner/name" format). */
-  async getSubscription(id: string, token?: string): Promise<IamSubscription | null> {
-    const resp = await this.request<IamApiResponse<IamSubscription>>(
-      "/api/get-subscription",
-      { params: { id }, token },
-    );
-    return resp.data ?? null;
-  }
-
-  /** Get the subscription for a specific user. */
-  async getUserSubscription(userId: string, token?: string): Promise<IamSubscription | null> {
-    const subs = await this.getSubscriptions(token);
-    return subs.find((s) => s.user === userId) ?? null;
-  }
-
-  // -----------------------------------------------------------------------
-  // Plans
-  // -----------------------------------------------------------------------
-
-  /** Get all plans for an owner. */
-  async getPlans(token?: string): Promise<IamPlan[]> {
-    const owner = this.orgName ?? "admin";
-    const resp = await this.request<IamApiResponse<IamPlan[]>>(
-      "/api/get-plans",
-      { params: { owner }, token },
-    );
-    return resp.data ?? [];
-  }
-
-  /** Get a specific plan by ID. */
-  async getPlan(id: string, token?: string): Promise<IamPlan | null> {
-    const resp = await this.request<IamApiResponse<IamPlan>>(
-      "/api/get-plan",
-      { params: { id }, token },
-    );
-    return resp.data ?? null;
-  }
-
-  // -----------------------------------------------------------------------
-  // Pricing
-  // -----------------------------------------------------------------------
-
-  /** Get all pricing configurations for an owner. */
-  async getPricings(token?: string): Promise<IamPricing[]> {
-    const owner = this.orgName ?? "admin";
-    const resp = await this.request<IamApiResponse<IamPricing[]>>(
-      "/api/get-pricings",
-      { params: { owner }, token },
-    );
-    return resp.data ?? [];
-  }
-
-  /** Get a specific pricing by ID. */
-  async getPricing(id: string, token?: string): Promise<IamPricing | null> {
-    const resp = await this.request<IamApiResponse<IamPricing>>(
-      "/api/get-pricing",
-      { params: { id }, token },
-    );
-    return resp.data ?? null;
-  }
-
-  // -----------------------------------------------------------------------
-  // Payments
-  // -----------------------------------------------------------------------
-
-  /** Get all payments for an owner. */
-  async getPayments(token?: string): Promise<IamPayment[]> {
-    const owner = this.orgName ?? "admin";
-    const resp = await this.request<IamApiResponse<IamPayment[]>>(
-      "/api/get-payments",
-      { params: { owner }, token },
-    );
-    return resp.data ?? [];
-  }
-
-  /** Get a specific payment by ID. */
-  async getPayment(id: string, token?: string): Promise<IamPayment | null> {
-    const resp = await this.request<IamApiResponse<IamPayment>>(
-      "/api/get-payment",
-      { params: { id }, token },
-    );
-    return resp.data ?? null;
-  }
-
-  // -----------------------------------------------------------------------
-  // Orders (if supported by IAM)
-  // -----------------------------------------------------------------------
-
-  /** Get all orders for an owner. */
-  async getOrders(token?: string): Promise<IamOrder[]> {
-    const owner = this.orgName ?? "admin";
-    const resp = await this.request<IamApiResponse<IamOrder[]>>(
-      "/api/get-orders",
-      { params: { owner }, token },
-    );
-    return resp.data ?? [];
-  }
-
-  /** Get a specific order by ID. */
-  async getOrder(id: string, token?: string): Promise<IamOrder | null> {
-    const resp = await this.request<IamApiResponse<IamOrder>>(
-      "/api/get-order",
-      { params: { id }, token },
-    );
-    return resp.data ?? null;
-  }
-
-  // -----------------------------------------------------------------------
-  // Convenience: check subscription status for an org
-  // -----------------------------------------------------------------------
-
-  /** Check if an org has an active subscription. */
-  async isSubscriptionActive(orgName: string, token?: string): Promise<{
-    active: boolean;
-    subscription: IamSubscription | null;
-    plan: IamPlan | null;
-  }> {
-    const subs = await this.getSubscriptions(token);
-    // Find subscription matching the org
-    const sub = subs.find(
-      (s) => s.owner === orgName && (s.state === "Active" || s.state === "active"),
-    ) ?? null;
-
-    if (!sub) {
-      return { active: false, subscription: null, plan: null };
-    }
+  async getBalance(user: string, currency = "usd", token?: string): Promise<Balance> {
+    return this.request("/api/v1/billing/balance", { params: { user, currency }, token });
+  }
 
-    let plan: IamPlan | null = null;
-    if (sub.plan) {
-      plan = await this.getPlan(sub.plan, token);
-    }
+  async getAllBalances(user: string, token?: string): Promise<Record<string, Balance>> {
+    return this.request("/api/v1/billing/balance/all", { params: { user }, token });
+  }
+
+  async addUsageRecord(record: { user: string; currency?: string; amount: number; model?: string; provider?: string; tokens?: number }, token?: string): Promise<Transaction> {
+    return this.request("/api/v1/billing/usage", { method: "POST", body: record, token });
+  }
+
+  async getUsageRecords(user: string, currency = "usd", token?: string): Promise<Transaction[]> {
+    return this.request("/api/v1/billing/usage", { params: { user, currency }, token });
+  }
+
+  async addDeposit(params: { user: string; currency?: string; amount: number; notes?: string; tags?: string[]; expiresIn?: string }, token?: string): Promise<Transaction> {
+    return this.request("/api/v1/billing/deposit", { method: "POST", body: params, token });
+  }
+
+  async grantStarterCredit(user: string, token?: string): Promise<Transaction> {
+    return this.request("/api/v1/billing/credit", { method: "POST", body: { user }, token });
+  }
 
-    return { active: true, subscription: sub, plan };
+  async subscribe(params: { planId: string; userId: string }, token?: string): Promise<Subscription> {
+    return this.request("/api/v1/subscribe", { method: "POST", body: params, token });
+  }
+
+  async getSubscription(id: string, token?: string): Promise<Subscription | null> {
+    try { return await this.request(`/api/v1/subscribe/${id}`, { token }); } catch { return null; }
+  }
+
+  async cancelSubscription(id: string, token?: string): Promise<void> {
+    await this.request(`/api/v1/subscribe/${id}`, { method: "DELETE", token });
+  }
+
+  async getPlans(token?: string): Promise<Plan[]> {
+    return this.request("/api/v1/plan", { token });
+  }
+
+  async getPlan(id: string, token?: string): Promise<Plan | null> {
+    try { return await this.request(`/api/v1/plan/${id}`, { token }); } catch { return null; }
+  }
+
+  async authorize(orderId: string, token?: string): Promise<Payment> {
+    return this.request(`/api/v1/authorize/${orderId}`, { method: "POST", token });
+  }
+
+  async capture(orderId: string, token?: string): Promise<Payment> {
+    return this.request(`/api/v1/capture/${orderId}`, { method: "POST", token });
+  }
+
+  async charge(orderId: string, token?: string): Promise<Payment> {
+    return this.request(`/api/v1/charge/${orderId}`, { method: "POST", token });
+  }
+
+  async refund(paymentId: string, token?: string): Promise<Payment> {
+    return this.request(`/api/v1/refund/${paymentId}`, { method: "POST", token });
   }
 }
+
+export class CommerceApiError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "CommerceApiError";
+    this.status = status;
+  }
+}
+
+// Backwards-compatible alias
+export { BillingClient as IamBillingClient };

package/src/client.ts

@@ -7,6 +7,7 @@ import type {
   IamApiResponse,
   IamUser,
   IamOrganization,
+  IamProject,
   OidcDiscovery,
   TokenResponse,
 } from "./types.js";
@@ -288,6 +289,41 @@ export class IamClient {
     return org ? [org] : [];
   }
 
+  // -----------------------------------------------------------------------
+  // Project
+  // -----------------------------------------------------------------------
+
+  /** List projects (for the configured owner). */
+  async getProjects(token?: string): Promise<IamProject[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamProject[]>>(
+      "/api/get-projects",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific project by ID ("owner/name" format). */
+  async getProject(id: string, token?: string): Promise<IamProject | null> {
+    const resp = await this.request<IamApiResponse<IamProject>>(
+      "/api/get-project",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  /** Get all projects for an organization. */
+  async getOrganizationProjects(
+    organization: string,
+    token?: string,
+  ): Promise<IamProject[]> {
+    const resp = await this.request<IamApiResponse<IamProject[]>>(
+      "/api/get-organization-projects",
+      { params: { organization }, token },
+    );
+    return resp.data ?? [];
+  }
+
   // -----------------------------------------------------------------------
   // Raw request (for extending)
   // -----------------------------------------------------------------------

package/src/index.ts

@@ -1,32 +1,34 @@
 /**
- * @hanzo/iam — TypeScript SDK for Hanzo IAM (Casdoor-based identity & access management).
+ * @hanzo/iam — TypeScript SDK for Hanzo IAM (identity & access management).
+ *
+ * Handles: auth (OIDC, JWT, PKCE), users, organizations, projects.
+ * Billing is backed by Commerce — the BillingClient talks to Commerce API.
  *
  * @example
  * ```ts
- * import { IamClient, IamBillingClient, validateToken } from "@hanzo/iam";
+ * import { IamClient, BillingClient, validateToken } from "@hanzo/iam";
  *
  * const client = new IamClient({
  *   serverUrl: "https://iam.hanzo.ai",
  *   clientId: "my-app",
  * });
  *
- * // Validate a JWT
- * const result = await validateToken(accessToken, {
- *   serverUrl: "https://iam.hanzo.ai",
- *   clientId: "my-app",
+ * const billing = new BillingClient({
+ *   commerceUrl: "https://commerce.hanzo.ai",
  * });
  * ```
  */
 
-// Core client
+// Core client (auth, users, orgs, projects → IAM)
 export { IamClient, IamApiError } from "./client.js";
 
+// Billing client (subscriptions, plans, payments, usage → Commerce API)
+// Canonical source: commerce.js/billing. Re-exported here for convenience.
+export { BillingClient, IamBillingClient, CommerceApiError } from "./billing.js";
+
 // JWT validation
 export { validateToken, clearJwksCache } from "./auth.js";
 
-// Billing client
-export { IamBillingClient } from "./billing.js";
-
 // Browser PKCE auth (re-exported from separate entry point too)
 export { BrowserIamSdk, type BrowserIamConfig } from "./browser.js";
 export { generatePkceChallenge, generateState } from "./pkce.js";
@@ -42,11 +44,21 @@ export type {
   IamJwtClaims,
   IamUser,
   IamOrganization,
+  IamProject,
+  Subscription,
+  Plan,
+  Pricing,
+  Payment,
+  Order,
+  UsageRecord,
+  UsageSummary,
   IamSubscription,
   IamPlan,
   IamPricing,
   IamPayment,
   IamOrder,
+  IamUsageRecord,
+  IamUsageSummary,
   IamAuthResult,
   IamApiResponse,
 } from "./types.js";

package/src/nextauth.ts

@@ -0,0 +1,93 @@
+/**
+ * NextAuth.js provider for Hanzo IAM (OIDC-based).
+ *
+ * Consolidates the HanzoIamProvider and IamProvider implementations
+ * so all Next.js apps can share one canonical implementation.
+ *
+ * @example
+ * ```ts
+ * // next-auth config
+ * import { HanzoIamProvider } from "@hanzo/iam/nextauth";
+ *
+ * export default NextAuth({
+ *   providers: [
+ *     HanzoIamProvider({
+ *       serverUrl: process.env.IAM_SERVER_URL!,
+ *       clientId: process.env.IAM_CLIENT_ID!,
+ *       clientSecret: process.env.IAM_CLIENT_SECRET!,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface HanzoIamProfile extends Record<string, unknown> {
+  sub: string;
+  name: string;
+  email: string;
+  preferred_username?: string;
+  picture?: string;
+  avatar?: string;
+  displayName?: string;
+  email_verified?: boolean;
+}
+
+/**
+ * NextAuth.js / Auth.js compatible OAuth provider for Hanzo IAM.
+ *
+ * Uses standard OIDC well-known endpoint for automatic configuration.
+ * JWT id_token validation (issuer, audience, signature) is handled by
+ * openid-client using the JWKS published at `{serverUrl}/.well-known/jwks`.
+ *
+ * Pass `checks: ["state", "pkce"]` in options for PKCE alignment.
+ */
+export function HanzoIamProvider<P extends HanzoIamProfile>(
+  options: {
+    serverUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    orgName?: string;
+    appName?: string;
+    /** OAuth state/PKCE checks. Default: ["state"]. Add "pkce" for extra security. */
+    checks?: ("state" | "pkce" | "nonce" | "none")[];
+    [key: string]: unknown;
+  },
+): Record<string, unknown> {
+  const issuer = options.serverUrl.replace(/\/$/, "");
+  const checks = options.checks ?? ["state"];
+
+  return {
+    id: "hanzo-iam",
+    name: "Hanzo IAM",
+    type: "oauth",
+    wellKnown: `${issuer}/.well-known/openid-configuration`,
+    idToken: true,
+    checks,
+    authorization: { params: { scope: "openid profile email" } },
+    profile(profile: P) {
+      return {
+        id: profile.sub,
+        name:
+          profile.displayName ||
+          profile.name ||
+          profile.preferred_username ||
+          profile.email ||
+          "",
+        email: profile.email,
+        image: profile.avatar || profile.picture || null,
+      };
+    },
+    style: {
+      bg: "#050508",
+      text: "#fff",
+      logo: "",
+    },
+    options,
+  };
+}
+
+// Re-export with alias for backwards compat
+export { HanzoIamProvider as IamProvider };
+export type { HanzoIamProfile };