@goodz-core/sdk 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,350 @@
+# @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 |
+
+## UI Components (React)
+
+The SDK includes a React component for displaying GoodZ collectibles with full material effects and tilt interaction — the same experience used on GoodZ.Core itself.
+
+### GoodZCardFocus
+
+A "tap to focus, then tilt" component that opens a full-screen modal with holographic effects, gyroscope support, and material-accurate rendering for all 10 form factors.
+
+```tsx
+import { GoodZCardFocus } from "@goodz-core/sdk/ui";
+
+<GoodZCardFocus
+  imageUrl="https://goodzcore.manus.space/api/shell/42.png"
+  cardName="Luna"
+  rarity="SSR"         // Controls holographic intensity
+  formFactor="trading_card"  // Controls material effect
+>
+  <img src={thumbnailUrl} alt="Luna" className="w-full rounded-lg" />
+</GoodZCardFocus>
+```
+
+**Supported form factors:** `trading_card`, `postcard`, `postcard_portrait`, `polaroid`, `laser_ticket`, `badge_small`, `badge_medium`, `badge_large`, `acrylic_stand_tall`, `acrylic_stand_chibi`.
+
+**Material effects by form factor:**
+
+| Form Factor | Material Effect |
+|---|---|
+| `trading_card` | Holographic gradient + sparkle (intensity by rarity) |
+| `postcard` / `postcard_portrait` | Paper texture + subtle shadow |
+| `polaroid` | White border (thick bottom) + paper texture |
+| `laser_ticket` | Intense rainbow holographic + shimmer animation |
+| `badge_*` | Circular clip + metal frame + dome highlight |
+| `acrylic_stand_*` | Transparent glass + edge refraction + caustic |
+
+**Interaction modes:**
+- Desktop: mouse position controls tilt (lerp-smoothed)
+- Mobile: gyroscope (auto-detected) or touch drag fallback
+- iOS: permission request button for gyroscope access
+
+**Requirements:** React 18+ and React DOM 18+ as peer dependencies. No CSS framework required — all styles are inline.
+
+### Form Factor Utilities
+
+```ts
+import { FORM_FACTORS, getAspectRatioCSS, getFormFactorSpec } from "@goodz-core/sdk/ui";
+
+getAspectRatioCSS("trading_card");  // "5 / 7"
+getAspectRatioCSS("badge_small");   // "1 / 1"
+
+const spec = getFormFactorSpec("polaroid");
+// { key: "polaroid", label: "Polaroid", aspectRatio: [3, 4], isCircle: false }
+```
+
+## 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";
+import { GoodZCardFocus } from "@goodz-core/sdk/ui";
+```
+
+The root import (`@goodz-core/sdk`) re-exports everything for convenience.
+
+## License
+
+MIT

package/dist/alive/index.d.ts

@@ -0,0 +1,175 @@
+import { X as TransportConfig } from '../transport-BOlScYEv.js';
+
+/**
+ * @goodz-core/sdk — Alive API Type Definitions
+ *
+ * Hand-crafted types mirroring the GoodZ.Alive MCP tool surface.
+ * Covers memory management, intimacy/affection, context building,
+ * and intent classification for AI-powered GoodZ companions.
+ *
+ * @module
+ */
+type MemoryType = "episodic" | "semantic" | "emotional";
+type IntentCategory = "chat" | "gift" | "trade" | "explore" | "care" | "customize" | "unknown";
+type MoodState = "happy" | "neutral" | "sad" | "excited" | "tired" | "curious" | "shy";
+interface AliveStoreMemoryInput {
+    /** The GoodZ card instance ID (the "alive" character) */
+    instanceId: number;
+    /** The user interacting with this character */
+    userId: number;
+    /** Type of memory to store */
+    memoryType: MemoryType;
+    /** The memory content */
+    content: string;
+    /** Importance score (0.0–1.0) — higher means more likely to be recalled */
+    importance?: number;
+    /** Optional tags for retrieval */
+    tags?: string[];
+}
+interface AliveMemory {
+    id: number;
+    instanceId: number;
+    userId: number;
+    memoryType: MemoryType;
+    content: string;
+    importance: number;
+    tags: string[];
+    createdAt: string;
+    lastRecalledAt: string | null;
+}
+interface AliveRecallMemoriesInput {
+    instanceId: number;
+    userId: number;
+    /** Natural language query to search memories */
+    query: string;
+    /** Max memories to return (default 10) */
+    limit?: number;
+    /** Filter by memory type */
+    memoryType?: MemoryType;
+}
+interface AliveForgetMemoryInput {
+    memoryId: number;
+    instanceId: number;
+    userId: number;
+}
+interface AliveGetIntimacyInput {
+    instanceId: number;
+    userId: number;
+}
+interface AliveIntimacy {
+    instanceId: number;
+    userId: number;
+    level: number;
+    totalInteractions: number;
+    lastInteractionAt: string | null;
+    mood: MoodState;
+    milestones: string[];
+}
+interface AliveUpdateIntimacyInput {
+    instanceId: number;
+    userId: number;
+    /** Delta to add/subtract from intimacy level */
+    delta: number;
+    /** Reason for the change */
+    reason: string;
+    /** Update the character's mood */
+    newMood?: MoodState;
+}
+interface AliveBuildContextInput {
+    instanceId: number;
+    userId: number;
+    /** The user's current message (used for memory retrieval) */
+    currentMessage?: string;
+    /** Include recent conversation history */
+    includeHistory?: boolean;
+    /** Max conversation turns to include (default 20) */
+    historyLimit?: number;
+}
+interface AliveContext {
+    /** The character's personality/soul from Core */
+    characterProfile: {
+        name: string;
+        personality: string | null;
+        worldview: string | null;
+        speakingStyle: string | null;
+        backstory: string | null;
+    };
+    /** Current intimacy state */
+    intimacy: AliveIntimacy;
+    /** Relevant memories retrieved for current context */
+    relevantMemories: AliveMemory[];
+    /** Recent conversation history */
+    recentHistory: Array<{
+        role: "user" | "character";
+        content: string;
+        timestamp: string;
+    }>;
+    /** System prompt assembled from all context */
+    systemPrompt: string;
+}
+interface AliveClassifyIntentInput {
+    instanceId: number;
+    userId: number;
+    /** The user's message to classify */
+    message: string;
+}
+interface AliveClassifiedIntent {
+    category: IntentCategory;
+    confidence: number;
+    /** Suggested action based on intent */
+    suggestedAction: string | null;
+    /** Extracted entities (e.g., card names, prices) */
+    entities: Record<string, any>;
+}
+interface AliveSendMessageInput {
+    instanceId: number;
+    userId: number;
+    message: string;
+    /** Optional: override the character's mood for this response */
+    moodOverride?: MoodState;
+}
+interface AliveChatResponse {
+    reply: string;
+    mood: MoodState;
+    intimacyDelta: number;
+    intent: AliveClassifiedIntent;
+    /** New memories formed from this interaction */
+    newMemories: string[];
+}
+
+/**
+ * @goodz-core/sdk — Alive Namespace
+ *
+ * Provides typed access to GoodZ.Alive MCP tools:
+ * memory management, intimacy/affection, context building,
+ * intent classification, and chat sessions.
+ *
+ * GoodZ.Alive gives each GoodZ card a "soul" — an AI-powered
+ * companion that remembers, grows, and responds uniquely.
+ *
+ * @module
+ */
+
+interface AliveNamespace {
+    /** Store a new memory for a character-user pair. */
+    storeMemory(input: AliveStoreMemoryInput): Promise<AliveMemory>;
+    /** Recall relevant memories using semantic search. */
+    recallMemories(input: AliveRecallMemoriesInput): Promise<AliveMemory[]>;
+    /** Delete a specific memory. */
+    forgetMemory(input: AliveForgetMemoryInput): Promise<any>;
+    /** Get the intimacy/affection state between a character and user. */
+    getIntimacy(input: AliveGetIntimacyInput): Promise<AliveIntimacy>;
+    /** Update intimacy level (e.g., after a positive/negative interaction). */
+    updateIntimacy(input: AliveUpdateIntimacyInput): Promise<AliveIntimacy>;
+    /** Build a full context object for AI generation (profile + memories + history + system prompt). */
+    buildContext(input: AliveBuildContextInput): Promise<AliveContext>;
+    /** Classify a user's message into an intent category. */
+    classifyIntent(input: AliveClassifyIntentInput): Promise<AliveClassifiedIntent>;
+    /** Send a message and get a character response (includes memory, intimacy, and intent processing). */
+    sendMessage(input: AliveSendMessageInput): Promise<AliveChatResponse>;
+    /** Call a raw MCP tool by name. Escape hatch for tools not yet in the typed API. */
+    rawTool<T = any>(toolName: string, args?: Record<string, any>): Promise<T>;
+}
+declare function createAliveNamespace(transport: TransportConfig): AliveNamespace;
+
+export { type AliveBuildContextInput, type AliveChatResponse, type AliveClassifiedIntent, type AliveClassifyIntentInput, type AliveContext, type AliveForgetMemoryInput, type AliveGetIntimacyInput, type AliveIntimacy, type AliveMemory, type AliveNamespace, type AliveRecallMemoriesInput, type AliveSendMessageInput, type AliveStoreMemoryInput, type AliveUpdateIntimacyInput, type IntentCategory, type MemoryType, type MoodState, createAliveNamespace };

package/dist/alive/index.js

@@ -0,0 +1,4 @@
+export { createAliveNamespace } from '../chunk-JAVMQXJM.js';
+import '../chunk-4SU7SU7K.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/alive/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}