@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/esm/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { LuChaptersDocument, LuCreateChapterDocument, LuCreateUniverseTranslationDocument, LuDraftDocument, LuDraftRecoveryDocument, LuIdentityDocument, LuImagePolicyDocument, LuProfileDocument, LuPublishChapterDocument, LuSaveDraftDocument, LuStoriesDocument, LuStoryDocument, LuUniverseDocument, LuUniversesDocument, LuUpdateUniverseTranslationDocument, LuValidateDraftDocument, } from './generated.js';
1
+ import { LuChaptersDocument, LuCreateChapterDocument, LuCreateEncyclopediaEntryDocument, LuCreateUniverseTranslationDocument, LuDeleteEncyclopediaEntryDocument, LuDraftDocument, LuDraftRecoveryDocument, LuEncyclopediaEntriesDocument, LuEncyclopediaEntryDocument, LuIdentityDocument, LuImagePolicyDocument, LuProfileDocument, LuPublishChapterDocument, LuRemoveChapterDocument, LuRenameChapterDocument, LuReorderChaptersDocument, LuSaveDraftDocument, LuSaveSeriesDocument, LuSeriesDocument, LuSetEncyclopediaEntryPublicationDocument, LuSetStoryVisibilityDocument, LuStoriesDocument, LuStoryDocument, LuTranslateEncyclopediaEntryDocument, LuUniverseDocument, LuUniversesDocument, LuUpdateEncyclopediaEntryDocument, LuUpdateStoryDocument, LuUpdateUniverseDocument, LuUpdateUniverseTranslationDocument, LuValidateDraftDocument, } from './generated.js';
2
2
  export { IMAGE_POLICY, } from './imagePolicy.js';
3
3
  export class LiteraryUniverseApiError extends Error {
4
4
  code;
@@ -6,15 +6,19 @@ export class LiteraryUniverseApiError extends Error {
6
6
  status;
7
7
  retryAfterSeconds;
8
8
  currentRevision;
9
+ resourceId;
9
10
  constructor(code, message, requestId, status, retryAfterSeconds,
10
11
  /** With VERSION_CONFLICT: the revision the resource is at now. */
11
- currentRevision) {
12
+ currentRevision,
13
+ /** With CONFLICT: the resource already holding the name. */
14
+ resourceId) {
12
15
  super(message);
13
16
  this.code = code;
14
17
  this.requestId = requestId;
15
18
  this.status = status;
16
19
  this.retryAfterSeconds = retryAfterSeconds;
17
20
  this.currentRevision = currentRevision;
21
+ this.resourceId = resourceId;
18
22
  this.name = 'LiteraryUniverseApiError';
19
23
  }
20
24
  }
@@ -105,6 +109,58 @@ export class LiteraryUniverseClient {
105
109
  updateUniverseTranslation(input, options) {
106
110
  return this.read(LuUpdateUniverseTranslationDocument, 'LuUpdateUniverseTranslation', input, options, undefined, 0);
107
111
  }
112
+ /** Changes a story's details; only the given fields change. */
113
+ updateStory(input, options) {
114
+ return this.read(LuUpdateStoryDocument, 'LuUpdateStory', input, options);
115
+ }
116
+ /** Hides a published story from readers (`PRIVATE`) or shows it again (`PUBLIC`). */
117
+ setStoryVisibility(input, options) {
118
+ return this.read(LuSetStoryVisibilityDocument, 'LuSetStoryVisibility', input, options);
119
+ }
120
+ renameChapter(input, options) {
121
+ return this.read(LuRenameChapterDocument, 'LuRenameChapter', { input }, options);
122
+ }
123
+ /** Removes a chapter never published and renumbers the rest. Not retried: a repeat finds nothing to remove. */
124
+ removeChapter(input, options) {
125
+ return this.read(LuRemoveChapterDocument, 'LuRemoveChapter', { input }, options, undefined, 0);
126
+ }
127
+ /** Puts every chapter of a story in the given order. */
128
+ reorderChapters(input, options) {
129
+ return this.read(LuReorderChaptersDocument, 'LuReorderChapters', { input }, options);
130
+ }
131
+ updateUniverse(input, options) {
132
+ return this.read(LuUpdateUniverseDocument, 'LuUpdateUniverse', input, options);
133
+ }
134
+ encyclopediaEntries(input, options) {
135
+ return this.read(LuEncyclopediaEntriesDocument, 'LuEncyclopediaEntries', input, options);
136
+ }
137
+ encyclopediaEntry(input, options) {
138
+ return this.read(LuEncyclopediaEntryDocument, 'LuEncyclopediaEntry', input, options);
139
+ }
140
+ /** Adds a draft entry. Fails with CONFLICT and `resourceId` when the name is taken; not retried. */
141
+ createEncyclopediaEntry(input, options) {
142
+ return this.read(LuCreateEncyclopediaEntryDocument, 'LuCreateEncyclopediaEntry', { input }, options, undefined, 0);
143
+ }
144
+ updateEncyclopediaEntry(input, options) {
145
+ return this.read(LuUpdateEncyclopediaEntryDocument, 'LuUpdateEncyclopediaEntry', input, options);
146
+ }
147
+ translateEncyclopediaEntry(input, options) {
148
+ return this.read(LuTranslateEncyclopediaEntryDocument, 'LuTranslateEncyclopediaEntry', { input }, options);
149
+ }
150
+ setEncyclopediaEntryPublication(input, options) {
151
+ return this.read(LuSetEncyclopediaEntryPublicationDocument, 'LuSetEncyclopediaEntryPublication', input, options);
152
+ }
153
+ /** Not retried: a repeat finds nothing to delete. */
154
+ deleteEncyclopediaEntry(input, options) {
155
+ return this.read(LuDeleteEncyclopediaEntryDocument, 'LuDeleteEncyclopediaEntry', input, options, undefined, 0);
156
+ }
157
+ series(input, options) {
158
+ return this.read(LuSeriesDocument, 'LuSeries', input, options);
159
+ }
160
+ /** Fails with VERSION_CONFLICT when the series changed since `expectedVersion`. */
161
+ saveSeries(input, options) {
162
+ return this.read(LuSaveSeriesDocument, 'LuSaveSeries', { input }, options, undefined, 0);
163
+ }
108
164
  saveDraft(input, options) {
109
165
  return this.read(LuSaveDraftDocument, 'LuSaveDraft', { input }, options);
110
166
  }
@@ -259,33 +315,7 @@ export class LiteraryUniverseClient {
259
315
  ? Number(retryHeader)
260
316
  : Math.max(0, Math.ceil((Date.parse(retryHeader) - Date.now()) / 1000))
261
317
  : undefined;
262
- const reader = response.body?.getReader();
263
- let bytes = 0;
264
- const chunks = [];
265
- if (reader) {
266
- try {
267
- while (true) {
268
- const chunk = await reader.read();
269
- if (chunk.done)
270
- break;
271
- bytes += chunk.value.byteLength;
272
- if (bytes > MAX_RESPONSE_BYTES) {
273
- await reader.cancel();
274
- throw new LiteraryUniverseApiError('PAYLOAD_TOO_LARGE', 'API response exceeds the read size limit', headerId, response.status);
275
- }
276
- chunks.push(chunk.value);
277
- }
278
- }
279
- finally {
280
- reader.releaseLock();
281
- }
282
- }
283
- const body = new Uint8Array(bytes);
284
- let offset = 0;
285
- for (const chunk of chunks) {
286
- body.set(chunk, offset);
287
- offset += chunk.byteLength;
288
- }
318
+ const body = await readResponseBytes(response, headerId);
289
319
  let envelope;
290
320
  try {
291
321
  envelope = JSON.parse(new TextDecoder().decode(body));
@@ -320,7 +350,9 @@ export class LiteraryUniverseClient {
320
350
  .replaceAll(token, '[redacted]')
321
351
  .slice(0, 500);
322
352
  const currentRevision = firstError?.extensions?.currentRevision;
323
- throw new LiteraryUniverseApiError(code, message, requestId, response.status, Number.isFinite(retryAfter) ? retryAfter : undefined, Number.isInteger(currentRevision) ? currentRevision : undefined);
353
+ throw new LiteraryUniverseApiError(code, message, requestId, response.status, Number.isFinite(retryAfter) ? retryAfter : undefined, Number.isInteger(currentRevision) ? currentRevision : undefined, typeof firstError?.extensions?.entryId === 'string'
354
+ ? firstError.extensions.entryId
355
+ : undefined);
324
356
  }
325
357
  const result = envelope?.data?.result;
326
358
  if (!result || typeof result !== 'object')
@@ -338,6 +370,42 @@ export class LiteraryUniverseClient {
338
370
  return credential.token;
339
371
  }
340
372
  }
373
+ const tooLarge = (response, requestId) => new LiteraryUniverseApiError('PAYLOAD_TOO_LARGE', 'API response exceeds the read size limit', requestId, response.status);
374
+ /** Streams when the body has a reader; a polyfilled Response without one is read whole. */
375
+ async function readResponseBytes(response, requestId) {
376
+ if (typeof response.body?.getReader !== 'function') {
377
+ const whole = new Uint8Array(await response.arrayBuffer());
378
+ if (whole.byteLength > MAX_RESPONSE_BYTES)
379
+ throw tooLarge(response, requestId);
380
+ return whole;
381
+ }
382
+ const reader = response.body.getReader();
383
+ let bytes = 0;
384
+ const chunks = [];
385
+ try {
386
+ while (true) {
387
+ const chunk = await reader.read();
388
+ if (chunk.done)
389
+ break;
390
+ bytes += chunk.value.byteLength;
391
+ if (bytes > MAX_RESPONSE_BYTES) {
392
+ await reader.cancel();
393
+ throw tooLarge(response, requestId);
394
+ }
395
+ chunks.push(chunk.value);
396
+ }
397
+ }
398
+ finally {
399
+ reader.releaseLock();
400
+ }
401
+ const body = new Uint8Array(bytes);
402
+ let offset = 0;
403
+ for (const chunk of chunks) {
404
+ body.set(chunk, offset);
405
+ offset += chunk.byteLength;
406
+ }
407
+ return body;
408
+ }
341
409
  /** REST routes answer `{ error }`; a JSON 404 there is a missing resource, not a wrong mount. */
342
410
  function restEnvelope(parsed, status) {
343
411
  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
+ };