@goodz-core/sdk 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,296 @@
+# @goodz-core/sdk
+
+Official SDK for **GoodZ.Core** — a type-safe API client for building GoodZ-powered applications. This package provides a zero-dependency HTTP client that speaks the tRPC wire protocol directly, along with OAuth helpers, Z-coin utilities, and full TypeScript type coverage.
+
+## Installation
+
+```bash
+npm install @goodz-core/sdk
+# or
+pnpm add @goodz-core/sdk
+```
+
+The SDK has only one runtime dependency (`superjson`) and requires Node.js 18+. It works in any JavaScript runtime that supports the Fetch API (Node.js, Deno, Bun, Cloudflare Workers, browsers).
+
+## Quick Start
+
+```ts
+import { createGoodZClient } from "@goodz-core/sdk";
+
+const goodz = createGoodZClient({
+  accessToken: "your-jwt-token",
+});
+
+// All methods are fully typed — IDE autocomplete works out of the box
+const balance = await goodz.zcoin.getMyBalance();
+console.log(`Balance: ${balance.balance} hundredths`);
+
+const result = await goodz.zcoin.commercialTransfer({
+  instanceId: 90447,
+  buyerUserId: 1,
+  sellerUserId: 2,
+  priceZcoin: 1050,       // 10.50 Z-coin in hundredths
+  saleType: "direct",
+  referenceId: "order-abc-123",
+  appClientId: "od_myapp",
+});
+console.log(`Trade ID: ${result.tradeId}`);
+```
+
+## Architecture
+
+The SDK is designed around three principles:
+
+**Zero tRPC dependency.** Unlike a typical tRPC client that requires `@trpc/client` and `@trpc/server` as peer dependencies (and transitively pulls in the entire server type tree), this SDK speaks the tRPC HTTP wire protocol directly using `fetch` + `superjson`. This means consumers never need to install tRPC packages, and the DTS bundle is fully self-contained.
+
+**Hand-crafted types as API contract.** All input/output types are defined inside the SDK itself (in `src/types.ts`), mirroring the Zod schemas on the Core server. This is the same approach used by the Stripe SDK — the types serve as both documentation and compile-time contract. When Core's API evolves, the SDK types are updated and a new version is published.
+
+**Namespace-based API surface.** Methods are organized into logical namespaces (`zcoin`, `inventory`, `collectible`, `user`, `auth`, `ip`) that mirror Core's tRPC router structure. Each namespace method is a thin wrapper around the transport layer, providing typed inputs and outputs.
+
+## API Reference
+
+### Client Configuration
+
+```ts
+interface GoodZClientConfig {
+  coreUrl?: string;           // Default: "https://goodzcore.manus.space"
+  accessToken?: string;       // Static JWT token
+  getAccessToken?: () => string | Promise<string>;  // Dynamic token provider
+  headers?: Record<string, string>;  // Custom headers for every request
+}
+```
+
+The `getAccessToken` function takes precedence over `accessToken` when both are provided. Use it for auto-refresh scenarios.
+
+### Namespaces
+
+#### `goodz.zcoin` — Z-coin Payment & Settlement
+
+The Z-coin namespace handles all monetary operations. These are the primary APIs that Commerce and Exchange apps use to process purchases.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getMyBalance()` | Query | Get authenticated user's Z-coin balance |
+| `getMyHistory(input?)` | Query | Get Z-coin transaction history with pagination |
+| `getDepositPackages(input?)` | Query | List available deposit packages with pricing |
+| `createDepositOrder(input)` | Mutation | Create a Stripe checkout session for Z-coin deposit |
+| `getDepositStatus(input)` | Query | Check deposit checkout session status |
+| `commercialTransfer(input)` | Mutation | Atomic Z-coin payment + ownership transfer |
+| `mintAndCharge(input)` | Mutation | Mint new instance + charge buyer atomically |
+| `chargeUser(input)` | Mutation | Charge user's Z-coin for in-app purchases |
+| `createDirectPurchaseOrder(input)` | Mutation | Create fiat-to-Z-coin direct purchase checkout |
+
+**Key method: `commercialTransfer`** is the primary API for all secondary market transactions. It atomically debits the buyer's Z-coin balance, credits the seller (minus platform fee), and transfers card instance ownership — all in a single database transaction. The `referenceId` parameter provides idempotency, so duplicate calls (e.g., from retries) return the same result.
+
+**Key method: `mintAndCharge`** is the primary API for primary sales (gacha, direct-from-creator). It mints a new card instance and charges the buyer in one atomic operation. Requires prior mint authorization via `inventory.grantMintAuth`.
+
+#### `goodz.inventory` — Card Instance Management
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getUserInventory(input)` | Query | Get a user's owned card instances |
+| `confirmOwnership(input)` | Query | Check if user owns a specific card |
+| `mint(input)` | Mutation | Mint new card instances (requires authorization) |
+| `transfer(input)` | Mutation | Transfer a specific instance to another user |
+| `transferByCard(input)` | Mutation | Transfer instances by cardId (oldest first) |
+| `grantMintAuth(input)` | Mutation | Grant mint authorization to another user/app |
+| `transferHistory(input)` | Query | Get transfer/ownership history |
+
+For commercial transactions (purchases, trades), always use `zcoin.commercialTransfer` or `zcoin.mintAndCharge` instead of the raw `transfer`/`mint` methods. The raw methods are intended for administrative operations and gift transfers only.
+
+#### `goodz.collectible` — Card & Instance Queries
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getInstanceById(input)` | Query | Get instance by numeric ID |
+| `getPublicInstance(input)` | Query | Get instance by instance code |
+| `getPublicInstancesBatch(input)` | Query | Batch-fetch instances (max 100) |
+| `getCardProfile(input)` | Query | Get card metadata, rarity, series info |
+| `getShellImageUrl(input)` | Query | Get shell (packaging) image URL |
+
+#### `goodz.user` — User Profiles
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getPublicProfile(input)` | Query | Get profile by openId |
+| `getPublicProfileById(input)` | Query | Get profile by internal userId |
+
+#### `goodz.auth` — Authentication
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `me()` | Query | Get authenticated user's profile |
+| `getOAuthAppInfo(input)` | Query | Get OAuth app info by client ID |
+
+#### `goodz.ip` — IP Management (Franchise/Series/Card)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getFranchise(input)` | Query | Get franchise by ID or slug |
+| `getSeries(input)` | Query | Get series by ID or slug |
+| `listSeriesByFranchise(input)` | Query | List all series in a franchise |
+| `getCard(input)` | Query | Get card by ID |
+| `listCardsBySeries(input)` | Query | List all cards in a series |
+
+### Raw Escape Hatches
+
+For routes not yet covered by the typed namespaces, use the raw methods:
+
+```ts
+const data = await goodz.rawQuery("some.newRoute", { id: 123 });
+const result = await goodz.rawMutation("some.newMutation", { name: "test" });
+```
+
+## Authentication
+
+### Server-to-Server with Static Token
+
+The simplest approach for backend services:
+
+```ts
+const goodz = createGoodZClient({
+  accessToken: process.env.CORE_ACCESS_TOKEN,
+});
+```
+
+### Auto-Refresh with TokenManager
+
+For long-running services that need automatic token refresh:
+
+```ts
+import { createGoodZClient } from "@goodz-core/sdk/core";
+import { TokenManager } from "@goodz-core/sdk/auth";
+
+const tokenManager = new TokenManager({
+  clientId: "od_myapp",
+  initialTokens: {
+    accessToken: savedAccessToken,
+    refreshToken: savedRefreshToken,
+    expiresAt: savedExpiresAt,
+  },
+  onTokenRefresh: async (tokens) => {
+    // Persist refreshed tokens to your database
+    await db.update(appTokens).set({
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAt: tokens.expiresAt,
+    });
+  },
+});
+
+const goodz = createGoodZClient({
+  getAccessToken: () => tokenManager.getValidToken(),
+});
+```
+
+### OAuth Authorization Code Flow
+
+For apps that authenticate users via GoodZ OAuth:
+
+```ts
+import { buildAuthorizationUrl, exchangeCode } from "@goodz-core/sdk/auth";
+
+// Step 1: Redirect user to authorization URL
+const authUrl = buildAuthorizationUrl({
+  clientId: "od_myapp",
+  redirectUri: "https://myapp.com/callback",
+  scope: "read write",
+  state: crypto.randomUUID(),
+});
+
+// Step 2: Exchange code for tokens in your callback handler
+const tokens = await exchangeCode({
+  clientId: "od_myapp",
+  clientSecret: process.env.CLIENT_SECRET,
+  code: searchParams.get("code"),
+  redirectUri: "https://myapp.com/callback",
+});
+
+// Step 3: Create a user-scoped client
+const userGoodz = createGoodZClient({
+  accessToken: tokens.accessToken,
+});
+```
+
+## Z-coin Precision
+
+GoodZ.Core stores Z-coin amounts in **hundredths** (1/100th of a Z-coin). For example, 10.50 Z-coin is stored as `1050`. The SDK provides utility functions to convert between display values and hundredths:
+
+```ts
+import { toHundredths, toDisplay, formatZcoin } from "@goodz-core/sdk/zcoin";
+
+toHundredths(10.50);    // → 1050
+toDisplay(1050);        // → 10.5
+formatZcoin(1050);      // → "10.50"
+```
+
+Always use `toHundredths()` when constructing API inputs to avoid the off-by-100x error:
+
+```ts
+// ✅ Correct
+await goodz.zcoin.commercialTransfer({
+  priceZcoin: toHundredths(10.50),  // 1050
+  // ...
+});
+
+// ❌ Wrong — this charges 0.10 Z-coin instead of 10.00
+await goodz.zcoin.commercialTransfer({
+  priceZcoin: 10,
+  // ...
+});
+```
+
+## Error Handling
+
+All API errors are thrown as `GoodZApiError` instances with structured fields:
+
+```ts
+import { GoodZApiError } from "@goodz-core/sdk";
+
+try {
+  await goodz.zcoin.commercialTransfer({ /* ... */ });
+} catch (err) {
+  if (err instanceof GoodZApiError) {
+    console.error(err.code);       // "BAD_REQUEST", "FORBIDDEN", "CONFLICT", etc.
+    console.error(err.httpStatus);  // 400, 403, 409, etc.
+    console.error(err.path);       // "zcoin.commercialTransfer"
+    console.error(err.message);    // Human-readable error message
+
+    // Zod validation errors (if input was malformed)
+    if (err.zodErrors) {
+      for (const fieldErr of err.zodErrors) {
+        console.error(`${fieldErr.path.join(".")}: ${fieldErr.message}`);
+      }
+    }
+
+    // Full detailed string for logging
+    console.error(err.toDetailedString());
+  }
+}
+```
+
+Common error codes and recommended handling:
+
+| Code | HTTP | Meaning | Recommended Action |
+|------|------|---------|--------------------|
+| `BAD_REQUEST` | 400 | Invalid input or insufficient balance | Check input values, show user-friendly message |
+| `UNAUTHORIZED` | 401 | Missing or invalid token | Redirect to login or refresh token |
+| `FORBIDDEN` | 403 | No permission (e.g., not the owner) | Show permission denied message |
+| `NOT_FOUND` | 404 | Resource doesn't exist | Show 404 page or fallback |
+| `CONFLICT` | 409 | Version conflict (optimistic locking) | Retry the operation |
+
+## Subpath Imports
+
+For tree-shaking, import from specific subpaths:
+
+```ts
+import { createGoodZClient } from "@goodz-core/sdk/core";
+import { TokenManager } from "@goodz-core/sdk/auth";
+import { toHundredths } from "@goodz-core/sdk/zcoin";
+```
+
+The root import (`@goodz-core/sdk`) re-exports everything for convenience.
+
+## License
+
+MIT