@brigadasos/nadeshiko-sdk 2.0.7-internal.5cdd62f → 2.1.0-internal

package/README.md

@@ -1,20 +1,11 @@
 # Nadeshiko SDK
 
-TypeScript SDK for the [Nadeshiko API](https://nadeshiko.co).
+TypeScript SDK for the [Nadeshiko API](https://nadeshiko.co). Full API reference at [nadeshiko.co/docs/api](https://nadeshiko.co/docs/api/index.html).
 
 ## 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 session-authenticated endpoints) via the `internal` dist-tag:
-
-```bash
-bun add @brigadasos/nadeshiko-sdk@internal
 ```
 
 ## Quick start
@@ -26,113 +17,115 @@ const client = createNadeshikoClient({
   apiKey: process.env.NADESHIKO_API_KEY!,
 });
 
-const { data } = await client.search({ body: { query: { search: '彼女' } } });
+const data = await client.search({ query: { search: '彼女' } });
 console.log(data.segments);
+// [
+//   {
+//     segmentPublicId: 'xK9mP2nQwR4t',
+//     mediaPublicId: 'steins-gate',
+//     episode: 1,
+//     startTimeMs: 62340,
+//     endTimeMs: 65180,
+//     textJa: { content: '彼女に会いたい' },
+//     textEn: { content: 'I want to see her' },
+//     urls: {
+//       imageUrl: 'https://...',
+//       audioUrl: 'https://...',
+//       videoUrl: 'https://...',
+//     },
+//   },
+//   // ...
+// ]
 ```
 
-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 public endpoints. The key is sent as `Authorization: Bearer <apiKey>`.
+Pass your API key to `createNadeshikoClient`. It is sent as `Authorization: Bearer <apiKey>` on every request.
 
 ```typescript
-import { createNadeshikoClient } from '@brigadasos/nadeshiko-sdk';
-
 const client = createNadeshikoClient({
   apiKey: process.env.NADESHIKO_API_KEY!,
-  baseURL: 'PRODUCTION', // 'LOCAL' | 'DEVELOPMENT' | 'PRODUCTION' | custom URL
-});
-```
-
-### Session token (user-authenticated endpoints, internal build only)
-
-The public package exposes only API-key-capable endpoints.
-For session-authenticated endpoints (`/v1/user/*`, `/v1/collections/*`), use the internal build.
-
-Pass a `sessionToken` getter that returns the value of the `nadeshiko.session_token` cookie — called fresh on every request.
-
-**Nuxt / Nitro server routes:**
-
-```typescript
-// server/utils/nadeshiko.ts
-import { createNadeshikoClient } from '@brigadasos/nadeshiko-sdk';
-import type { H3Event } from 'h3';
-
-export function useNadeshikoClient(event: H3Event) {
-  return createNadeshikoClient({
-    sessionToken: () => getCookie(event, 'nadeshiko.session_token'),
-  });
-}
-```
-
-```typescript
-// server/api/preferences.get.ts
-export default defineEventHandler(async (event) => {
-  const client = useNadeshikoClient(event);
-  return client.getUserPreferences();
+  baseURL: 'PRODUCTION'
 });
 ```
 
-**Browser note:** if your session cookie is `HttpOnly`, use same-origin proxy routes and let the browser attach cookies automatically.
+## Available endpoints
+
+### Search
+| Method | Description |
+|---|---|
+| `search(params?)` | Search segments by query, with filters and sorting |
+| `getSearchStats(params?)` | Category counts and media list for filter UI |
+| `searchWords(params)` | Look up multiple words and get match counts per media |
+| `searchMedia(params)` | Find media by name (autocomplete) |
+
+### Stats
+| Method | Description |
+|---|---|
+| `getStatsOverview()` | Corpus-wide stats: segment count, media count, coverage tiers |
+
+### Media
+| Method | Description |
+|---|---|
+| `listMedia(params?)` | Browse the media catalog |
+| `getMedia(id)` | Get a single media entry by public ID |
+| `listEpisodes(params)` | List episodes for a media entry |
+| `getEpisode(params)` | Get a single episode |
+| `getSegment(id)` | Get a single segment by UUID |
+| `getSegmentContext(id)` | Get segments surrounding a given segment |
+
+### User
+| Method | Description |
+|---|---|
+| `getMe()` | Current user profile and API quota |
+| `listUserActivity(params?)` | Activity history (searches, plays, exports) |
+| `getUserActivityHeatmap(params?)` | Daily activity counts for a heatmap |
+| `getUserActivityStats(params?)` | Aggregate stats over a date range |
+| `listExcludedMedia()` | Media hidden from search results |
+| `addExcludedMedia(params)` | Hide a media entry from search results |
+| `removeExcludedMedia(id)` | Un-hide a media entry |
+
+### Collections
+| Method | Description |
+|---|---|
+| `listCollections(params?)` | List your saved collections |
+| `createCollection(params)` | Create a new collection |
+| `getCollection(id)` | Get a collection and its segments |
+| `deleteCollection(id)` | Delete a collection |
+| `addSegmentToCollection(params)` | Add a segment to a collection |
+| `searchCollectionSegments(params)` | Search within a collection |
+| `removeSegmentFromCollection(params)` | Remove a segment from a collection |
 
 ## Error handling
 
-Errors throw a `NadeshikoError` — a proper `Error` subclass with all RFC 7807 Problem Details fields available directly.
+Errors throw a `NadeshikoError`. A proper `Error` subclass with all RFC 7807 Problem Details fields.
 
 ```typescript
-import { createNadeshikoClient, NadeshikoError } from '@brigadasos/nadeshiko-sdk';
-
-const client = createNadeshikoClient({ apiKey: process.env.NADESHIKO_API_KEY! });
+import { NadeshikoError } from '@brigadasos/nadeshiko-sdk';
 
 try {
-  const { data } = await client.search({ body: { query: { search: '食べる' } } });
+  const data = await client.search({ 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');
+        console.error('Authentication failed:', err.detail);
         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');
+        console.error('Rate limited — 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;
     }
@@ -148,20 +141,20 @@ try {
 | `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 |
+| `traceId` | `string \| undefined` | Trace ID — 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`:
+Pass `throwOnError: false` to get a `{ data, error }` result instead of throwing:
 
 ```typescript
 const result = await client.search({
   throwOnError: false,
-  body: { query: { search: '猫' } },
+  query: { search: '猫' },
 });
 
-if (result.error) {
+if ('error' in result) {
   console.error(result.error);
 } else {
   console.log(result.data.segments);
@@ -170,7 +163,7 @@ if (result.error) {
 
 ## 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`:
+The client retries automatically on network errors and `408 / 429 / 500 / 502 / 503 / 504` responses. `429` responses with a `Retry-After` header are respected.
 
 ```typescript
 const client = createNadeshikoClient({
@@ -186,33 +179,38 @@ const client = createNadeshikoClient({
 
 ## Pagination
 
-Use `paginate()` to iterate through all pages without manual cursor tracking:
+Paginated endpoints have a `.paginate()` method that returns an async iterator over individual items:
 
 ```typescript
-import { createNadeshikoClient, paginate } from '@brigadasos/nadeshiko-sdk';
-
-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 }),
-)) {
+for await (const segment of client.search.paginate({
+  query: { search: '猫' },
+})) {
   console.log(segment.textJa.content);
 }
+
+for await (const media of client.listMedia.paginate()) {
+  console.log(media.nameEn);
+}
 ```
 
-`paginate()` works with any endpoint that returns `{ pagination: { hasMore, cursor } }`:
+For manual page-by-page control, use the `cursor` field:
 
 ```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);
-}
+let cursor: string | undefined;
+
+do {
+  const data = await client.search({
+    query: { search: '犬' },
+    take: 10,
+    cursor,
+  });
+
+  for (const segment of data.segments) {
+    console.log(segment.textJa.content);
+  }
+
+  cursor = data.pagination.hasMore ? data.pagination.cursor : undefined;
+} while (cursor);
 ```
 
 See [`examples/examples.ts`](examples/examples.ts) for more usage patterns.

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 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 type NadeshikoErrorCode = Error400['code'] | Error401['code'] | Error403['code'] | Error429['code'] | Error500['code'] | Error409['code'] | Error404['code'] | 'UNKNOWN_ERROR';
 export interface NadeshikoProblemDetails {
     code: NadeshikoErrorCode;
     title: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../generated/internal/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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../generated/internal/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,GAAG,eAAe,CAAC;AAEtL,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"}