@brigadasos/nadeshiko-sdk 1.5.1-dev.e889ab8 → 2.0.0-dev.384ecdc

package/README.md

@@ -5,41 +5,54 @@ TypeScript SDK for the [Nadeshiko API](https://nadeshiko.co).
 ## Install
 
 ```bash
+# npm / pnpm / bun
+npm add @brigadasos/nadeshiko-sdk
+pnpm add @brigadasos/nadeshiko-sdk
 bun add @brigadasos/nadeshiko-sdk
 ```
 
-Install the internal build (includes internal + session-authenticated endpoints) via the `internal` dist-tag:
+Install the internal build (includes session-authenticated endpoints) via the `internal` dist-tag:
 
 ```bash
 bun add @brigadasos/nadeshiko-sdk@internal
 ```
 
+## Quick start
+
+```typescript
+import { createNadeshikoClient } from '@brigadasos/nadeshiko-sdk';
+
+const client = createNadeshikoClient({
+  apiKey: process.env.NADESHIKO_API_KEY!,
+});
+
+const { data } = await client.search({ body: { query: { search: '彼女' } } });
+console.log(data.segments);
+```
+
+Errors throw by default. Wrap calls you want to handle explicitly in `try/catch`.
+
 ## Authentication
 
 ### API key (server-to-server)
 
-Use an API key for endpoints that don't require a user session. The key is sent as `Authorization: Bearer <apiKey>`.
+Use an API key for public endpoints. The key is sent as `Authorization: Bearer <apiKey>`.
 
 ```typescript
-import { createNadeshikoClient, search } from '@brigadasos/nadeshiko-sdk';
+import { createNadeshikoClient } from '@brigadasos/nadeshiko-sdk';
 
 const client = createNadeshikoClient({
   apiKey: process.env.NADESHIKO_API_KEY!,
-  baseUrl: 'PRODUCTION',
-});
-
-const result = await search({
-  client,
-  body: { query: { search: '彼女' } },
+  baseURL: 'PRODUCTION', // 'LOCAL' | 'DEVELOPMENT' | 'PRODUCTION' | custom URL
 });
 ```
 
 ### Session token (user-authenticated endpoints, internal build only)
 
-The default public package intentionally exposes API-key-capable endpoints only.
-For session-authenticated endpoints (for example `/v1/user/*` and `/v1/collections/*`), use the internal build.
+The public package exposes only API-key-capable endpoints.
+For session-authenticated endpoints (`/v1/user/*`, `/v1/collections/*`), use the internal build.
 
-Endpoints under `/v1/user/*` and `/v1/collections/*` require a user session. Pass a `sessionToken` getter that returns the value of the `nadeshiko.session_token` cookie — called fresh on every request.
+Pass a `sessionToken` getter that returns the value of the `nadeshiko.session_token` cookie — called fresh on every request.
 
 **Nuxt / Nitro server routes:**
 
@@ -63,100 +76,142 @@ export default defineEventHandler(async (event) => {
 });
 ```
 
-**Browser note:** if your session cookie is `HttpOnly`, use same-origin proxy routes and let the browser attach cookies automatically. Prefer server-side session handling for internal endpoints.
+**Browser note:** if your session cookie is `HttpOnly`, use same-origin proxy routes and let the browser attach cookies automatically.
 
-### Error handling
+## Error handling
 
-Every response returns a discriminated union with either `data` or `error`. The `error` object follows the [RFC 7807](https://tools.ietf.org/html/rfc7807) Problem Details format, so you always get a machine-readable `code` and a human-readable `detail`.
+Errors throw a `NadeshikoError` — a proper `Error` subclass with all RFC 7807 Problem Details fields available directly.
 
 ```typescript
-import { createNadeshikoClient, search } from '@brigadasos/nadeshiko-sdk';
+import { createNadeshikoClient, NadeshikoError } from '@brigadasos/nadeshiko-sdk';
 
-const client = createNadeshikoClient({
-  apiKey: process.env.NADESHIKO_API_KEY!,
-  baseUrl: 'PRODUCTION',
-});
+const client = createNadeshikoClient({ apiKey: process.env.NADESHIKO_API_KEY! });
+
+try {
+  const { data } = await client.search({ body: { query: { search: '食べる' } } });
+  console.log(data.segments);
+} catch (err) {
+  if (err instanceof NadeshikoError) {
+    switch (err.code) {
+      // 400 — Bad Request
+      case 'VALIDATION_FAILED':
+        console.error('Validation failed:', err.detail);
+        for (const [field, msg] of Object.entries(err.errors ?? {})) {
+          console.error(`  ${field}: ${msg}`);
+        }
+        break;
+      case 'INVALID_JSON':
+      case 'INVALID_REQUEST':
+        console.error('Bad request:', err.detail);
+        break;
+
+      // 401 — Unauthorized
+      case 'AUTH_CREDENTIALS_REQUIRED':
+        console.error('Missing API key');
+        break;
+      case 'AUTH_CREDENTIALS_INVALID':
+        console.error('API key is invalid');
+        break;
+      case 'AUTH_CREDENTIALS_EXPIRED':
+        console.error('Token has expired, re-authenticate');
+        break;
+
+      // 403 — Forbidden
+      case 'ACCESS_DENIED':
+      case 'INSUFFICIENT_PERMISSIONS':
+        console.error('Access denied');
+        break;
+
+      // 429 — Too Many Requests
+      case 'RATE_LIMIT_EXCEEDED':
+        console.error('Rate limit hit, slow down');
+        break;
+      case 'QUOTA_EXCEEDED':
+        console.error('Monthly quota exhausted');
+        break;
+
+      // 500 — Internal Server Error
+      case 'INTERNAL_SERVER_EXCEPTION':
+        // err.traceId is the instance field — include when reporting issues
+        console.error('Server error, trace ID:', err.traceId);
+        break;
+    }
+  }
+}
+```
 
-const result = await search({
-  client,
-  body: { query: { search: '食べる' } },
+**`NadeshikoError` fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `code` | `string` | Machine-readable error code |
+| `title` | `string` | Short summary |
+| `detail` | `string` | Human-readable explanation |
+| `status` | `number` | HTTP status code |
+| `traceId` | `string \| undefined` | Trace ID for this error — include when reporting issues |
+| `errors` | `Record<string, string> \| undefined` | Per-field messages (`VALIDATION_FAILED` only) |
+
+### Opt out of throwing per-call
+
+If you need the old `{ data, error }` return shape for a specific call, pass `throwOnError: false`:
+
+```typescript
+const result = await client.search({
+  throwOnError: false,
+  body: { query: { search: '猫' } },
 });
 
 if (result.error) {
-  switch (result.error.code) {
-    // 400 — Bad Request
-    case 'VALIDATION_FAILED':
-      console.error('Validation failed:', result.error.detail);
-      for (const [field, msg] of Object.entries(result.error.errors ?? {})) {
-        console.error(`  ${field}: ${msg}`);
-      }
-      break;
-    case 'INVALID_JSON':
-      console.error('Malformed JSON body:', result.error.detail);
-      break;
-    case 'INVALID_REQUEST':
-      console.error('Invalid request:', result.error.detail);
-      break;
-
-    // 401 — Unauthorized
-    case 'AUTH_CREDENTIALS_REQUIRED':
-      console.error('Missing API key or session token');
-      break;
-    case 'AUTH_CREDENTIALS_INVALID':
-      console.error('API key is invalid');
-      break;
-    case 'AUTH_CREDENTIALS_EXPIRED':
-      console.error('Token has expired, re-authenticate');
-      break;
-    case 'EMAIL_NOT_VERIFIED':
-      console.error('Email verification required');
-      break;
-
-    // 403 — Forbidden
-    case 'ACCESS_DENIED':
-      console.error('Access denied');
-      break;
-    case 'INSUFFICIENT_PERMISSIONS':
-      console.error('API key lacks the required scope');
-      break;
-
-    // 429 — Too Many Requests
-    case 'RATE_LIMIT_EXCEEDED':
-      console.error('Rate limit hit, slow down');
-      break;
-    case 'QUOTA_EXCEEDED':
-      console.error('Monthly quota exhausted');
-      break;
-
-    // 500 — Internal Server Error
-    case 'INTERNAL_SERVER_EXCEPTION':
-      console.error('Server error, trace ID:', result.error.instance);
-      break;
-  }
-  return;
+  console.error(result.error);
+} else {
+  console.log(result.data.segments);
 }
+```
 
-// result.data is fully typed as SearchResponse
-for (const segment of result.data.segments ?? []) {
-  console.log(segment.content.ja.content);
-}
+## Retry and timeout
+
+The client retries automatically on network errors and `408 / 429 / 500 / 502 / 503 / 504` responses. `429` responses with a `Retry-After` header are respected. Configure via `retryOptions`:
+
+```typescript
+const client = createNadeshikoClient({
+  apiKey: process.env.NADESHIKO_API_KEY!,
+  retryOptions: {
+    maxRetries: 3,        // default: 2
+    initialDelayMs: 1000, // default: 500 — doubles with each attempt
+    maxDelayMs: 30_000,   // default: 30_000
+    timeout: 10_000,      // per-attempt timeout in ms (default: none)
+  },
+});
 ```
 
-### `throwOnError` mode
+## Pagination
 
-If you prefer exceptions over checking `.error`, pass `throwOnError: true`. The call will throw on any non-2xx response, and the return type narrows to just `{ data }`.
+Use `paginate()` to iterate through all pages without manual cursor tracking:
 
 ```typescript
-try {
-  const { data } = await search({
-    client,
-    throwOnError: true,
-    body: { query: { search: '彼女' } },
-  });
+import { createNadeshikoClient, paginate } from '@brigadasos/nadeshiko-sdk';
 
-  console.log(data.segments);
-} catch (error) {
-  console.error('Request failed:', error);
+const client = createNadeshikoClient({ apiKey: process.env.NADESHIKO_API_KEY! });
+
+for await (const segment of paginate(
+  (opts) => client.search(opts),
+  { body: { query: { search: '猫' } } },
+  (data) => ({ items: data.segments, pagination: data.pagination }),
+)) {
+  console.log(segment.textJa.content);
+}
+```
+
+`paginate()` works with any endpoint that returns `{ pagination: { hasMore, cursor } }`:
+
+```typescript
+// Browse all media
+for await (const media of paginate(
+  (opts) => client.listMedia(opts),
+  {},
+  (data) => ({ items: data.media, pagination: data.pagination }),
+)) {
+  console.log(media.nameEn);
 }
 ```
 

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+import type { Error400, Error401, Error403, Error429, Error500, Error409, Error404 } from './types.gen';
+/** Union of all known API error codes. */
+export type NadeshikoErrorCode = Error400['code'] | Error401['code'] | Error403['code'] | Error429['code'] | Error500['code'] | Error409['code'] | Error404['code'];
+export interface NadeshikoProblemDetails {
+    code: NadeshikoErrorCode;
+    title: string;
+    detail: string;
+    type?: string;
+    /** Trace ID for this specific error occurrence — include when reporting issues */
+    instance?: string;
+    status: number;
+    /** Per-field validation messages, present when `code` is `'VALIDATION_FAILED'` */
+    errors?: Record<string, string>;
+}
+/**
+ * Thrown by the SDK when the API returns a non-2xx response.
+ *
+ * All fields from the RFC 7807 Problem Details response body are
+ * available directly on the error instance.
+ *
+ * @example
+ * ```ts
+ * import { NadeshikoError } from '@brigadasos/nadeshiko-sdk';
+ *
+ * try {
+ *   const { data } = await client.search({ body: { query: { search: '猫' } } });
+ * } catch (err) {
+ *   if (err instanceof NadeshikoError) {
+ *     console.error(err.code);    // 'RATE_LIMIT_EXCEEDED'
+ *     console.error(err.status);  // 429
+ *     console.error(err.traceId); // trace ID for support
+ *   }
+ * }
+ * ```
+ */
+export declare class NadeshikoError extends Error {
+    readonly code: NadeshikoErrorCode;
+    readonly title: string;
+    readonly detail: string;
+    readonly type?: string;
+    readonly status: number;
+    /** Trace ID from `instance` field — include when reporting issues */
+    readonly traceId?: string;
+    /** Per-field validation messages, present when `code === 'VALIDATION_FAILED'` */
+    readonly errors?: Record<string, string>;
+    constructor(body: NadeshikoProblemDetails);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../generated/dev/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExG,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEpK,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAE7B,IAAI,EAAE,uBAAuB;CAW1C"}