@literary-universe/sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import { type AuthorChapterCreateInput, type AuthorChapterPublishInput, type AuthorDraftSaveInput, type LuChaptersQueryVariables, type LuCreateUniverseTranslationMutationVariables, type LuDraftQueryVariables, type LuDraftRecoveryQueryVariables, type LuStoriesQueryVariables, type LuStoryQueryVariables, type LuUniverseQueryVariables, type LuUniversesQueryVariables, type LuUpdateUniverseTranslationMutationVariables } from './generated.js';
1
+ import { type AuthorChapterCreateInput, type AuthorChapterPublishInput, type AuthorChapterRemoveInput, type AuthorChapterRenameInput, type AuthorChapterReorderInput, type AuthorDraftSaveInput, type AuthorEncyclopediaEntryCreateInput, type AuthorEncyclopediaEntryTranslationInput, type AuthorSeriesSaveInput, type LuChaptersQueryVariables, type LuCreateUniverseTranslationMutationVariables, type LuDeleteEncyclopediaEntryMutationVariables, type LuDraftQueryVariables, type LuDraftRecoveryQueryVariables, type LuEncyclopediaEntriesQueryVariables, type LuEncyclopediaEntryQueryVariables, type LuSeriesQueryVariables, type LuSetEncyclopediaEntryPublicationMutationVariables, type LuSetStoryVisibilityMutationVariables, type LuStoriesQueryVariables, type LuStoryQueryVariables, type LuUniverseQueryVariables, type LuUniversesQueryVariables, type LuUpdateEncyclopediaEntryMutationVariables, type LuUpdateStoryMutationVariables, type LuUpdateUniverseMutationVariables, type LuUpdateUniverseTranslationMutationVariables } from './generated.js';
2
2
  export type * from './generated.js';
3
3
  export type { JsonValue } from './json.js';
4
4
  import type { ImagePolicy, ImagePurpose } from './imagePolicy.js';
@@ -30,9 +30,13 @@ export declare class LiteraryUniverseApiError extends Error {
30
30
  readonly retryAfterSeconds?: number | undefined;
31
31
  /** With VERSION_CONFLICT: the revision the resource is at now. */
32
32
  readonly currentRevision?: number | undefined;
33
+ /** With CONFLICT: the resource already holding the name. */
34
+ readonly resourceId?: string | undefined;
33
35
  constructor(code: string, message: string, requestId?: string | undefined, status?: number | undefined, retryAfterSeconds?: number | undefined,
34
36
  /** With VERSION_CONFLICT: the revision the resource is at now. */
35
- currentRevision?: number | undefined);
37
+ currentRevision?: number | undefined,
38
+ /** With CONFLICT: the resource already holding the name. */
39
+ resourceId?: string | undefined);
36
40
  }
37
41
  export type RequestOptions = {
38
42
  signal?: AbortSignal;
@@ -211,6 +215,257 @@ export declare class LiteraryUniverseClient {
211
215
  description: string | null;
212
216
  revision: number;
213
217
  }>;
218
+ /** Changes a story's details; only the given fields change. */
219
+ updateStory(input: LuUpdateStoryMutationVariables, options?: RequestOptions): Promise<{
220
+ id: string;
221
+ title: string;
222
+ slug: string | null;
223
+ language: string;
224
+ universeId: string | null;
225
+ organizationId: string | null;
226
+ createdAt: string | null;
227
+ updatedAt: string | null;
228
+ publishedAt: string | null;
229
+ privateAt: string | null;
230
+ state: import("./generated.js").AuthorWorkState;
231
+ }>;
232
+ /** Hides a published story from readers (`PRIVATE`) or shows it again (`PUBLIC`). */
233
+ setStoryVisibility(input: LuSetStoryVisibilityMutationVariables, options?: RequestOptions): Promise<{
234
+ id: string;
235
+ title: string;
236
+ slug: string | null;
237
+ language: string;
238
+ universeId: string | null;
239
+ organizationId: string | null;
240
+ createdAt: string | null;
241
+ updatedAt: string | null;
242
+ publishedAt: string | null;
243
+ privateAt: string | null;
244
+ state: import("./generated.js").AuthorWorkState;
245
+ }>;
246
+ renameChapter(input: AuthorChapterRenameInput, options?: RequestOptions): Promise<{
247
+ id: string;
248
+ storyId: string;
249
+ sequence: number;
250
+ title: string;
251
+ language: string;
252
+ hasDraft: boolean;
253
+ updatedAt: string | null;
254
+ publishedAt: string | null;
255
+ }>;
256
+ /** Removes a chapter never published and renumbers the rest. Not retried: a repeat finds nothing to remove. */
257
+ removeChapter(input: AuthorChapterRemoveInput, options?: RequestOptions): Promise<{
258
+ id: string;
259
+ storyId: string;
260
+ }>;
261
+ /** Puts every chapter of a story in the given order. */
262
+ reorderChapters(input: AuthorChapterReorderInput, options?: RequestOptions): Promise<{
263
+ storyId: string;
264
+ chapterIds: Array<string>;
265
+ }>;
266
+ updateUniverse(input: LuUpdateUniverseMutationVariables, options?: RequestOptions): Promise<{
267
+ id: string;
268
+ title: string;
269
+ slug: string | null;
270
+ language: string;
271
+ organizationId: string | null;
272
+ createdAt: string | null;
273
+ updatedAt: string | null;
274
+ publishedAt: string | null;
275
+ privateAt: string | null;
276
+ state: import("./generated.js").AuthorWorkState;
277
+ }>;
278
+ encyclopediaEntries(input: LuEncyclopediaEntriesQueryVariables, options?: RequestOptions): Promise<{
279
+ nodes: Array<{
280
+ id: string;
281
+ universeId: string;
282
+ name: string;
283
+ categoryId: string;
284
+ categoryTitle: string | null;
285
+ language: string;
286
+ wip: boolean;
287
+ publishedAt: string | null;
288
+ updatedAt: string | null;
289
+ translations: Array<string>;
290
+ }>;
291
+ pageInfo: {
292
+ endCursor: string | null;
293
+ hasNextPage: boolean;
294
+ };
295
+ }>;
296
+ encyclopediaEntry(input: LuEncyclopediaEntryQueryVariables, options?: RequestOptions): Promise<{
297
+ id: string;
298
+ universeId: string;
299
+ name: string;
300
+ categoryId: string;
301
+ categoryTitle: string | null;
302
+ language: string;
303
+ wip: boolean;
304
+ publishedAt: string | null;
305
+ updatedAt: string | null;
306
+ translations: Array<string>;
307
+ pronunciation: string | null;
308
+ tags: Array<string>;
309
+ summary: string | null;
310
+ parent: {
311
+ id: string | null;
312
+ name: string;
313
+ } | null;
314
+ related: Array<{
315
+ id: string | null;
316
+ name: string;
317
+ }>;
318
+ fields: Array<{
319
+ id: string;
320
+ title: string;
321
+ type: string;
322
+ private: boolean;
323
+ text: string | null;
324
+ }>;
325
+ }>;
326
+ /** Adds a draft entry. Fails with CONFLICT and `resourceId` when the name is taken; not retried. */
327
+ createEncyclopediaEntry(input: AuthorEncyclopediaEntryCreateInput, options?: RequestOptions): Promise<{
328
+ id: string;
329
+ universeId: string;
330
+ name: string;
331
+ categoryId: string;
332
+ categoryTitle: string | null;
333
+ language: string;
334
+ wip: boolean;
335
+ publishedAt: string | null;
336
+ updatedAt: string | null;
337
+ translations: Array<string>;
338
+ pronunciation: string | null;
339
+ tags: Array<string>;
340
+ summary: string | null;
341
+ parent: {
342
+ id: string | null;
343
+ name: string;
344
+ } | null;
345
+ related: Array<{
346
+ id: string | null;
347
+ name: string;
348
+ }>;
349
+ fields: Array<{
350
+ id: string;
351
+ title: string;
352
+ type: string;
353
+ private: boolean;
354
+ text: string | null;
355
+ }>;
356
+ }>;
357
+ updateEncyclopediaEntry(input: LuUpdateEncyclopediaEntryMutationVariables, options?: RequestOptions): Promise<{
358
+ id: string;
359
+ universeId: string;
360
+ name: string;
361
+ categoryId: string;
362
+ categoryTitle: string | null;
363
+ language: string;
364
+ wip: boolean;
365
+ publishedAt: string | null;
366
+ updatedAt: string | null;
367
+ translations: Array<string>;
368
+ pronunciation: string | null;
369
+ tags: Array<string>;
370
+ summary: string | null;
371
+ parent: {
372
+ id: string | null;
373
+ name: string;
374
+ } | null;
375
+ related: Array<{
376
+ id: string | null;
377
+ name: string;
378
+ }>;
379
+ fields: Array<{
380
+ id: string;
381
+ title: string;
382
+ type: string;
383
+ private: boolean;
384
+ text: string | null;
385
+ }>;
386
+ }>;
387
+ translateEncyclopediaEntry(input: AuthorEncyclopediaEntryTranslationInput, options?: RequestOptions): Promise<{
388
+ id: string;
389
+ universeId: string;
390
+ name: string;
391
+ categoryId: string;
392
+ categoryTitle: string | null;
393
+ language: string;
394
+ wip: boolean;
395
+ publishedAt: string | null;
396
+ updatedAt: string | null;
397
+ translations: Array<string>;
398
+ pronunciation: string | null;
399
+ tags: Array<string>;
400
+ summary: string | null;
401
+ parent: {
402
+ id: string | null;
403
+ name: string;
404
+ } | null;
405
+ related: Array<{
406
+ id: string | null;
407
+ name: string;
408
+ }>;
409
+ fields: Array<{
410
+ id: string;
411
+ title: string;
412
+ type: string;
413
+ private: boolean;
414
+ text: string | null;
415
+ }>;
416
+ }>;
417
+ setEncyclopediaEntryPublication(input: LuSetEncyclopediaEntryPublicationMutationVariables, options?: RequestOptions): Promise<{
418
+ id: string;
419
+ universeId: string;
420
+ name: string;
421
+ categoryId: string;
422
+ categoryTitle: string | null;
423
+ language: string;
424
+ wip: boolean;
425
+ publishedAt: string | null;
426
+ updatedAt: string | null;
427
+ translations: Array<string>;
428
+ pronunciation: string | null;
429
+ tags: Array<string>;
430
+ summary: string | null;
431
+ parent: {
432
+ id: string | null;
433
+ name: string;
434
+ } | null;
435
+ related: Array<{
436
+ id: string | null;
437
+ name: string;
438
+ }>;
439
+ fields: Array<{
440
+ id: string;
441
+ title: string;
442
+ type: string;
443
+ private: boolean;
444
+ text: string | null;
445
+ }>;
446
+ }>;
447
+ /** Not retried: a repeat finds nothing to delete. */
448
+ deleteEncyclopediaEntry(input: LuDeleteEncyclopediaEntryMutationVariables, options?: RequestOptions): Promise<{
449
+ id: string;
450
+ universeId: string;
451
+ }>;
452
+ series(input: LuSeriesQueryVariables, options?: RequestOptions): Promise<{
453
+ id: string;
454
+ universeId: string;
455
+ title: string;
456
+ version: number;
457
+ storyIds: Array<string>;
458
+ updatedAt: string | null;
459
+ }[]>;
460
+ /** Fails with VERSION_CONFLICT when the series changed since `expectedVersion`. */
461
+ saveSeries(input: AuthorSeriesSaveInput, options?: RequestOptions): Promise<{
462
+ id: string;
463
+ universeId: string;
464
+ title: string;
465
+ version: number;
466
+ storyIds: Array<string>;
467
+ updatedAt: string | null;
468
+ }>;
214
469
  saveDraft(input: AuthorDraftSaveInput, options?: RequestOptions): Promise<{
215
470
  version: string;
216
471
  recoveryId: string;
package/dist/cjs/index.js CHANGED
@@ -10,15 +10,19 @@ class LiteraryUniverseApiError extends Error {
10
10
  status;
11
11
  retryAfterSeconds;
12
12
  currentRevision;
13
+ resourceId;
13
14
  constructor(code, message, requestId, status, retryAfterSeconds,
14
15
  /** With VERSION_CONFLICT: the revision the resource is at now. */
15
- currentRevision) {
16
+ currentRevision,
17
+ /** With CONFLICT: the resource already holding the name. */
18
+ resourceId) {
16
19
  super(message);
17
20
  this.code = code;
18
21
  this.requestId = requestId;
19
22
  this.status = status;
20
23
  this.retryAfterSeconds = retryAfterSeconds;
21
24
  this.currentRevision = currentRevision;
25
+ this.resourceId = resourceId;
22
26
  this.name = 'LiteraryUniverseApiError';
23
27
  }
24
28
  }
@@ -110,6 +114,58 @@ class LiteraryUniverseClient {
110
114
  updateUniverseTranslation(input, options) {
111
115
  return this.read(generated_js_1.LuUpdateUniverseTranslationDocument, 'LuUpdateUniverseTranslation', input, options, undefined, 0);
112
116
  }
117
+ /** Changes a story's details; only the given fields change. */
118
+ updateStory(input, options) {
119
+ return this.read(generated_js_1.LuUpdateStoryDocument, 'LuUpdateStory', input, options);
120
+ }
121
+ /** Hides a published story from readers (`PRIVATE`) or shows it again (`PUBLIC`). */
122
+ setStoryVisibility(input, options) {
123
+ return this.read(generated_js_1.LuSetStoryVisibilityDocument, 'LuSetStoryVisibility', input, options);
124
+ }
125
+ renameChapter(input, options) {
126
+ return this.read(generated_js_1.LuRenameChapterDocument, 'LuRenameChapter', { input }, options);
127
+ }
128
+ /** Removes a chapter never published and renumbers the rest. Not retried: a repeat finds nothing to remove. */
129
+ removeChapter(input, options) {
130
+ return this.read(generated_js_1.LuRemoveChapterDocument, 'LuRemoveChapter', { input }, options, undefined, 0);
131
+ }
132
+ /** Puts every chapter of a story in the given order. */
133
+ reorderChapters(input, options) {
134
+ return this.read(generated_js_1.LuReorderChaptersDocument, 'LuReorderChapters', { input }, options);
135
+ }
136
+ updateUniverse(input, options) {
137
+ return this.read(generated_js_1.LuUpdateUniverseDocument, 'LuUpdateUniverse', input, options);
138
+ }
139
+ encyclopediaEntries(input, options) {
140
+ return this.read(generated_js_1.LuEncyclopediaEntriesDocument, 'LuEncyclopediaEntries', input, options);
141
+ }
142
+ encyclopediaEntry(input, options) {
143
+ return this.read(generated_js_1.LuEncyclopediaEntryDocument, 'LuEncyclopediaEntry', input, options);
144
+ }
145
+ /** Adds a draft entry. Fails with CONFLICT and `resourceId` when the name is taken; not retried. */
146
+ createEncyclopediaEntry(input, options) {
147
+ return this.read(generated_js_1.LuCreateEncyclopediaEntryDocument, 'LuCreateEncyclopediaEntry', { input }, options, undefined, 0);
148
+ }
149
+ updateEncyclopediaEntry(input, options) {
150
+ return this.read(generated_js_1.LuUpdateEncyclopediaEntryDocument, 'LuUpdateEncyclopediaEntry', input, options);
151
+ }
152
+ translateEncyclopediaEntry(input, options) {
153
+ return this.read(generated_js_1.LuTranslateEncyclopediaEntryDocument, 'LuTranslateEncyclopediaEntry', { input }, options);
154
+ }
155
+ setEncyclopediaEntryPublication(input, options) {
156
+ return this.read(generated_js_1.LuSetEncyclopediaEntryPublicationDocument, 'LuSetEncyclopediaEntryPublication', input, options);
157
+ }
158
+ /** Not retried: a repeat finds nothing to delete. */
159
+ deleteEncyclopediaEntry(input, options) {
160
+ return this.read(generated_js_1.LuDeleteEncyclopediaEntryDocument, 'LuDeleteEncyclopediaEntry', input, options, undefined, 0);
161
+ }
162
+ series(input, options) {
163
+ return this.read(generated_js_1.LuSeriesDocument, 'LuSeries', input, options);
164
+ }
165
+ /** Fails with VERSION_CONFLICT when the series changed since `expectedVersion`. */
166
+ saveSeries(input, options) {
167
+ return this.read(generated_js_1.LuSaveSeriesDocument, 'LuSaveSeries', { input }, options, undefined, 0);
168
+ }
113
169
  saveDraft(input, options) {
114
170
  return this.read(generated_js_1.LuSaveDraftDocument, 'LuSaveDraft', { input }, options);
115
171
  }
@@ -264,33 +320,7 @@ class LiteraryUniverseClient {
264
320
  ? Number(retryHeader)
265
321
  : Math.max(0, Math.ceil((Date.parse(retryHeader) - Date.now()) / 1000))
266
322
  : undefined;
267
- const reader = response.body?.getReader();
268
- let bytes = 0;
269
- const chunks = [];
270
- if (reader) {
271
- try {
272
- while (true) {
273
- const chunk = await reader.read();
274
- if (chunk.done)
275
- break;
276
- bytes += chunk.value.byteLength;
277
- if (bytes > MAX_RESPONSE_BYTES) {
278
- await reader.cancel();
279
- throw new LiteraryUniverseApiError('PAYLOAD_TOO_LARGE', 'API response exceeds the read size limit', headerId, response.status);
280
- }
281
- chunks.push(chunk.value);
282
- }
283
- }
284
- finally {
285
- reader.releaseLock();
286
- }
287
- }
288
- const body = new Uint8Array(bytes);
289
- let offset = 0;
290
- for (const chunk of chunks) {
291
- body.set(chunk, offset);
292
- offset += chunk.byteLength;
293
- }
323
+ const body = await readResponseBytes(response, headerId);
294
324
  let envelope;
295
325
  try {
296
326
  envelope = JSON.parse(new TextDecoder().decode(body));
@@ -325,7 +355,9 @@ class LiteraryUniverseClient {
325
355
  .replaceAll(token, '[redacted]')
326
356
  .slice(0, 500);
327
357
  const currentRevision = firstError?.extensions?.currentRevision;
328
- throw new LiteraryUniverseApiError(code, message, requestId, response.status, Number.isFinite(retryAfter) ? retryAfter : undefined, Number.isInteger(currentRevision) ? currentRevision : undefined);
358
+ throw new LiteraryUniverseApiError(code, message, requestId, response.status, Number.isFinite(retryAfter) ? retryAfter : undefined, Number.isInteger(currentRevision) ? currentRevision : undefined, typeof firstError?.extensions?.entryId === 'string'
359
+ ? firstError.extensions.entryId
360
+ : undefined);
329
361
  }
330
362
  const result = envelope?.data?.result;
331
363
  if (!result || typeof result !== 'object')
@@ -344,6 +376,42 @@ class LiteraryUniverseClient {
344
376
  }
345
377
  }
346
378
  exports.LiteraryUniverseClient = LiteraryUniverseClient;
379
+ const tooLarge = (response, requestId) => new LiteraryUniverseApiError('PAYLOAD_TOO_LARGE', 'API response exceeds the read size limit', requestId, response.status);
380
+ /** Streams when the body has a reader; a polyfilled Response without one is read whole. */
381
+ async function readResponseBytes(response, requestId) {
382
+ if (typeof response.body?.getReader !== 'function') {
383
+ const whole = new Uint8Array(await response.arrayBuffer());
384
+ if (whole.byteLength > MAX_RESPONSE_BYTES)
385
+ throw tooLarge(response, requestId);
386
+ return whole;
387
+ }
388
+ const reader = response.body.getReader();
389
+ let bytes = 0;
390
+ const chunks = [];
391
+ try {
392
+ while (true) {
393
+ const chunk = await reader.read();
394
+ if (chunk.done)
395
+ break;
396
+ bytes += chunk.value.byteLength;
397
+ if (bytes > MAX_RESPONSE_BYTES) {
398
+ await reader.cancel();
399
+ throw tooLarge(response, requestId);
400
+ }
401
+ chunks.push(chunk.value);
402
+ }
403
+ }
404
+ finally {
405
+ reader.releaseLock();
406
+ }
407
+ const body = new Uint8Array(bytes);
408
+ let offset = 0;
409
+ for (const chunk of chunks) {
410
+ body.set(chunk, offset);
411
+ offset += chunk.byteLength;
412
+ }
413
+ return body;
414
+ }
347
415
  /** REST routes answer `{ error }`; a JSON 404 there is a missing resource, not a wrong mount. */
348
416
  function restEnvelope(parsed, status) {
349
417
  const { error } = parsed;
@@ -0,0 +1,20 @@
1
+ import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import { type LiteraryUniverseClient } from './index.js';
3
+ export type McpToolOptions = {
4
+ /** The signed-in client, or null when the agent is not logged in. */
5
+ client: () => LiteraryUniverseClient | null;
6
+ /** Categories and/or tool names to register; 'all' for every tool. Defaults to DEFAULT_TOOL_SELECTION. */
7
+ tools?: readonly string[];
8
+ docsBaseUrl?: string;
9
+ fetch?: typeof globalThis.fetch;
10
+ /** Enables set-cover from a local path; stdio servers only. */
11
+ readLocalFile?: (path: string) => Promise<Uint8Array>;
12
+ };
13
+ export declare const TOOL_CATEGORIES: Record<string, readonly string[]>;
14
+ export declare const DEFAULT_TOOL_SELECTION: readonly string[];
15
+ /** Expands categories and tool names into tool names; throws on an unknown entry. */
16
+ export declare function selectTools(selection: readonly string[] | undefined): string[];
17
+ /** Registers the selected tools and the story/draft resources on an MCP server. */
18
+ export declare function registerLiteraryUniverseTools(server: McpServer, options: McpToolOptions): {
19
+ registered: string[];
20
+ };