@major-tech/resource-client 0.1.3 → 0.1.5

package/README.md

@@ -1,90 +1,162 @@
 # @major-tech/resource-client
 
-TypeScript client for Major resources (PostgreSQL, Custom APIs, HubSpot, S3). Type-safe, zero dependencies, universal (Node/browser/edge), ESM & CJS.
+TS client: PostgreSQL/CustomAPI/HubSpot/S3. Type-safe, 0-dep, universal (Node/browser/edge), ESM+CJS.
 
 ## Install
 ```bash
-pnpm install @major-tech/resource-client
+pnpm add @major-tech/resource-client
 ```
 
-## Usage
-
-**Config (all clients):**
+## Config (All Clients)
 ```typescript
 { baseUrl: string; applicationId: string; resourceId: string; majorJwtToken?: string; fetch?: typeof fetch }
 ```
 
-**Response:** `{ ok: true; requestId: string; result: T } | { ok: false; requestId: string; error: { message: string; httpStatus?: number } }`
+## Response Format
+```typescript
+{ ok: true; requestId: string; result: T } | { ok: false; requestId: string; error: { message: string; httpStatus?: number } }
+```
+
+## PostgresResourceClient
+
+**Constructor:** `new PostgresResourceClient(config: BaseClientConfig)`
 
-**PostgreSQL:**
+**Method:** `invoke(sql: string, params: DbParamPrimitive[] | undefined, invocationKey: string, timeoutMs?: number): Promise<DatabaseInvokeResponse>`
+
+**Params:**
+- `sql`: SQL query string
+- `params`: `(string | number | boolean | null)[]` - positional params ($1, $2, etc)
+- `invocationKey`: unique operation ID (regex: `[a-zA-Z0-9][a-zA-Z0-9._:-]*`)
+- `timeoutMs`: optional timeout
+
+**Result (ok=true):**
+```typescript
+{ kind: "database"; rows: Record<string, unknown>[]; rowsAffected?: number }
+```
+
+**Example:**
 ```typescript
 import { PostgresResourceClient } from '@major-tech/resource-client';
-const client = new PostgresResourceClient({ baseUrl, applicationId, resourceId, majorJwtToken? });
-const res = await client.invoke('SELECT * FROM users WHERE id = $1', [123], 'fetch-user-by-id');
-// res.ok ? res.result.rows / res.result.rowsAffected : res.error.message
+const c = new PostgresResourceClient({ baseUrl, applicationId, resourceId, majorJwtToken });
+const r = await c.invoke('SELECT * FROM users WHERE id = $1', [123], 'fetch-user');
+// r.ok ? r.result.rows : r.error.message
+```
+
+## CustomApiResourceClient
+
+**Constructor:** `new CustomApiResourceClient(config: BaseClientConfig)`
+
+**Method:** `invoke(method: HttpMethod, path: string, invocationKey: string, options?: { query?: QueryParams; headers?: Record<string, string>; body?: BodyPayload; timeoutMs?: number }): Promise<ApiInvokeResponse>`
+
+**Params:**
+- `method`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE"`
+- `path`: URL path (appended to resource baseUrl)
+- `invocationKey`: unique operation ID
+- `options.query`: `Record<string, string | string[]>` - query params
+- `options.headers`: `Record<string, string>` - additional headers
+- `options.body`: `{ type: "json"; value: unknown } | { type: "text"; value: string } | { type: "bytes"; base64: string; contentType: string }`
+- `options.timeoutMs`: timeout (default: 30000)
+
+**Result (ok=true):**
+```typescript
+{ kind: "api"; status: number; body: { kind: "json"; value: unknown } | { kind: "text"; value: string } | { kind: "bytes"; base64: string; contentType: string } }
 ```
 
-**Custom API:**
+**Example:**
 ```typescript
 import { CustomApiResourceClient } from '@major-tech/resource-client';
-const client = new CustomApiResourceClient({ baseUrl, applicationId, resourceId });
-const res = await client.invoke('POST', '/v1/payments', 'create-payment', {
-  query: { currency: 'USD' }, headers: { 'X-Custom': 'value' },
-  body: { type: 'json', value: { amount: 100 } }, timeoutMs: 5000
+const c = new CustomApiResourceClient({ baseUrl, applicationId, resourceId });
+const r = await c.invoke('POST', '/v1/pay', 'create-pay', {
+  query: { currency: 'USD' }, headers: { 'X-Key': 'val' },
+  body: { type: 'json', value: { amt: 100 } }, timeoutMs: 5000
 });
-// res.ok ? res.result.status / res.result.body : res.error
+// r.ok ? r.result.status : r.error
 ```
 
-**HubSpot:**
+## HubSpotResourceClient
+
+**Constructor:** `new HubSpotResourceClient(config: BaseClientConfig)`
+
+**Method:** `invoke(method: HttpMethod, path: string, invocationKey: string, options?: { query?: QueryParams; body?: { type: "json"; value: unknown }; timeoutMs?: number }): Promise<ApiInvokeResponse>`
+
+**Params:**
+- `method`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE"`
+- `path`: HubSpot API path
+- `invocationKey`: unique operation ID
+- `options.query`: `Record<string, string | string[]>`
+- `options.body`: `{ type: "json"; value: unknown }` - JSON only
+- `options.timeoutMs`: timeout (default: 30000)
+
+**Result:** Same as CustomApiResourceClient
+
+**Example:**
 ```typescript
 import { HubSpotResourceClient } from '@major-tech/resource-client';
-const client = new HubSpotResourceClient({ baseUrl, applicationId, resourceId });
-const res = await client.invoke('GET', '/crm/v3/objects/contacts', 'fetch-contacts', { query: { limit: '10' } });
-// res.ok && res.result.body.kind === 'json' ? res.result.body.value : res.error
+const c = new HubSpotResourceClient({ baseUrl, applicationId, resourceId });
+const r = await c.invoke('GET', '/crm/v3/objects/contacts', 'fetch-contacts', { query: { limit: '10' } });
+// r.ok && r.result.body.kind === 'json' ? r.result.body.value : r.error
 ```
 
-**S3:**
+## S3ResourceClient
+
+**Constructor:** `new S3ResourceClient(config: BaseClientConfig)`
+
+**Method:** `invoke(command: S3Command, params: Record<string, unknown>, invocationKey: string, options?: { timeoutMs?: number }): Promise<StorageInvokeResponse>`
+
+**Params:**
+- `command`: `"ListObjectsV2" | "HeadObject" | "GetObjectTagging" | "PutObjectTagging" | "DeleteObject" | "DeleteObjects" | "CopyObject" | "ListBuckets" | "GetBucketLocation" | "GeneratePresignedUrl"`
+- `params`: Command-specific params (e.g., `{ Bucket, Prefix, Key, expiresIn }`)
+- `invocationKey`: unique operation ID
+- `options.timeoutMs`: optional timeout
+
+**Result (ok=true):**
+```typescript
+{ kind: "storage"; command: string; data: unknown } | { kind: "storage"; presignedUrl: string; expiresAt: string }
+```
+- Standard commands return `{ kind: "storage"; command; data }`
+- `GeneratePresignedUrl` returns `{ kind: "storage"; presignedUrl; expiresAt }`
+
+**Example:**
 ```typescript
 import { S3ResourceClient } from '@major-tech/resource-client';
-const client = new S3ResourceClient({ baseUrl, applicationId, resourceId });
-const res = await client.invoke('ListObjectsV2', { Bucket: 'my-bucket', Prefix: 'uploads/' }, 'list-uploads');
-// res.ok ? res.result.data : res.error
-const url = await client.invoke('GeneratePresignedUrl', { Bucket: 'my-bucket', Key: 'file.pdf', expiresIn: 3600 }, 'presigned-url');
-// url.ok && 'presignedUrl' in url.result ? url.result.presignedUrl / url.result.expiresAt : url.error
+const c = new S3ResourceClient({ baseUrl, applicationId, resourceId });
+const r = await c.invoke('ListObjectsV2', { Bucket: 'my-bucket', Prefix: 'uploads/' }, 'list-uploads');
+// r.ok ? r.result.data : r.error
+const u = await c.invoke('GeneratePresignedUrl', { Bucket: 'my-bucket', Key: 'file.pdf', expiresIn: 3600 }, 'presigned');
+// u.ok && 'presignedUrl' in u.result ? u.result.presignedUrl : u.error
 ```
 
-**Error Handling:**
+## Error Handling
 ```typescript
 import { ResourceInvokeError } from '@major-tech/resource-client';
 try { await client.invoke(...); }
 catch (e) { if (e instanceof ResourceInvokeError) { e.message, e.httpStatus, e.requestId } }
 ```
 
-**Invocation Keys:** Unique operation identifiers for tracking (format: `[a-zA-Z0-9][a-zA-Z0-9._:-]*`). Examples: `fetch-user-by-id`, `create-payment`, `hubspot:get-contacts`, `s3.list-uploads`
-
-**Types:** All exported: `BaseClientConfig`, `DatabaseInvokeResponse`, `ApiInvokeResponse`, `StorageInvokeResponse`, `HttpMethod`, `QueryParams`, `BodyPayload`, `S3Command`, etc.
+## CLI - Singleton Generator
 
-## 🛠️ CLI Tool - Generate Singleton Clients
+**Commands:**
+- `npx major-client add <resourceId> <name> <type> <desc> <appId>` - Add resource, generate singleton
+- `npx major-client list` - List all resources
+- `npx major-client remove <name>` - Remove resource
+- `npx major-client regenerate` - Regenerate all clients
 
-The package includes a CLI tool to generate pre-configured singleton clients for your resources:
+**Types:** `database-postgresql | api-custom | api-hubspot | storage-s3`
 
-```bash
-# Add a resource
-npx major-client add "resource-123" "orders-db" "database-postgresql" "Orders database" "app-456"
+**Generated Files:**
+- `resources.json` - Resource registry
+- `src/clients/<name>.ts` - Singleton client
+- `src/clients/index.ts` - Exports
 
-# List all resources
-npx major-client list
+**Env Vars:** `MAJOR_API_BASE_URL`, `MAJOR_JWT_TOKEN`
 
-# Remove a resource
-npx major-client remove "orders-db"
+**Example:**
+```bash
+npx major-client add "res_123" "orders-db" "database-postgresql" "Orders DB" "app_456"
 ```
-
-This generates TypeScript files in `src/clients/` that you can import:
 ```typescript
 import { ordersDbClient } from './clients';
-const result = await ordersDbClient.invoke('SELECT * FROM orders', [], 'list-orders');
+const r = await ordersDbClient.invoke('SELECT * FROM orders', [], 'list-orders');
 ```
 
-**Types:** `database-postgresql` | `api-custom` | `api-hubspot` | `storage-s3`
-
 MIT License

package/bin/generate-clients.mjs

@@ -45,7 +45,7 @@ function clientTemplate(data) {
  * DO NOT EDIT - Auto-generated by @major-tech/resource-client
  */
 
-const BASE_URL = import.meta.env.MAJOR_API_BASE_URL || 'https://api.major.tech';
+const BASE_URL = import.meta.env.MAJOR_API_BASE_URL || 'https://api.prod.major.build';
 const MAJOR_JWT_TOKEN = import.meta.env.MAJOR_JWT_TOKEN;
 
 class ${data.clientName}Singleton {
@@ -58,6 +58,7 @@ class ${data.clientName}Singleton {
         majorJwtToken: MAJOR_JWT_TOKEN,
         applicationId: '${data.applicationId}',
         resourceId: '${data.resourceId}',
+        fetch: (...args) => fetch(...args),
       });
     }
     return ${data.clientName}Singleton.instance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@major-tech/resource-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "TypeScript client library for invoking Major resources (PostgreSQL, Custom APIs, HubSpot, S3)",
   "type": "module",
   "sideEffects": false,