@storypane/sdk 0.0.0-stage → 0.1.0-rc.2
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.
- package/LICENSE +21 -0
- package/README.md +647 -2
- package/bin/manage.mjs +241 -0
- package/bin/mcp.mjs +80 -0
- package/bin/migrations.mjs +523 -0
- package/bin/storypane.mjs +117 -0
- package/dist/codegen.d.ts +4 -0
- package/dist/codegen.js +145 -0
- package/dist/index.d.ts +40 -0
- package/dist/index.js +94 -0
- package/dist/management.d.ts +147 -0
- package/dist/management.js +141 -0
- package/dist/media.d.ts +17 -0
- package/dist/media.js +36 -0
- package/dist/migration-warning.d.ts +2 -0
- package/dist/migration-warning.js +13 -0
- package/dist/preview.d.ts +17 -0
- package/dist/preview.js +209 -0
- package/dist/react.d.ts +17 -0
- package/dist/react.js +66 -0
- package/dist/rich-text.d.ts +6 -0
- package/dist/rich-text.js +90 -0
- package/dist/types.d.ts +112 -0
- package/dist/types.js +33 -0
- package/package.json +76 -4
package/bin/manage.mjs
ADDED
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { readFile, rename, rm } from 'node:fs/promises';
|
|
2
|
+
import { createWriteStream } from 'node:fs';
|
|
3
|
+
import { basename } from 'node:path';
|
|
4
|
+
import { Readable } from 'node:stream';
|
|
5
|
+
import { pipeline } from 'node:stream/promises';
|
|
6
|
+
import { randomUUID } from 'node:crypto';
|
|
7
|
+
import { createManagementClient } from '../dist/management.js';
|
|
8
|
+
|
|
9
|
+
const actions = {
|
|
10
|
+
stories: ['list', 'get', 'create', 'update', 'delete'],
|
|
11
|
+
folders: ['list', 'create', 'update', 'delete'],
|
|
12
|
+
locales: ['list', 'create', 'update', 'delete'],
|
|
13
|
+
datasources: ['list', 'create', 'update'],
|
|
14
|
+
roles: ['list', 'create', 'update', 'delete'],
|
|
15
|
+
invitations: ['list', 'create', 'delete'],
|
|
16
|
+
webhooks: ['list', 'create', 'update', 'delete'],
|
|
17
|
+
assets: ['list', 'get', 'update', 'delete'],
|
|
18
|
+
space: ['get', 'update'],
|
|
19
|
+
};
|
|
20
|
+
const resources = new Set(Object.keys(actions));
|
|
21
|
+
export const managementCommands = new Set([
|
|
22
|
+
...resources,
|
|
23
|
+
'space',
|
|
24
|
+
'schemas',
|
|
25
|
+
'content',
|
|
26
|
+
'assets',
|
|
27
|
+
'api',
|
|
28
|
+
]);
|
|
29
|
+
export const managementHelp = `storypane stories list|get|create|update|delete [id] [--input file|-]
|
|
30
|
+
storypane folders|locales|roles|webhooks list|create|update|delete [id] [--input file|-]
|
|
31
|
+
storypane datasources list|create|update [id] [--input file|-]
|
|
32
|
+
storypane invitations list|create|delete [id] [--input file|-]
|
|
33
|
+
storypane space get|update [--input file|-]
|
|
34
|
+
storypane schemas list
|
|
35
|
+
storypane content get|save|publish|command <storyId> <localeId> [blockId] [--input file|-]
|
|
36
|
+
storypane assets list|get|update|delete [id] [--input file|-]
|
|
37
|
+
storypane assets upload <file> --mime <content-type>
|
|
38
|
+
storypane assets download <id> --out <file>
|
|
39
|
+
storypane api <GET|POST|PUT|PATCH|DELETE|HEAD> </resource/path> [--input file|-] [--out file]
|
|
40
|
+
|
|
41
|
+
Management commands use STORYPANE_URL, STORYPANE_SPACE_ID, STORYPANE_MANAGEMENT_TOKEN.
|
|
42
|
+
Use --json for compact JSON, --offset/--limit for lists (--cursor for assets), and --yes for deletes,
|
|
43
|
+
publishing, raw commands, and generic API writes. JSON input may come from stdin (-).
|
|
44
|
+
Story updates change name/location using the existing location contract.
|
|
45
|
+
Create scoped tokens in Settings → API & preview → Management API.`;
|
|
46
|
+
|
|
47
|
+
async function inputFile(file) {
|
|
48
|
+
if (!file) {
|
|
49
|
+
throw new Error('Provide --input <file> or --input - for JSON from stdin');
|
|
50
|
+
}
|
|
51
|
+
let text = '';
|
|
52
|
+
if (file === '-') {
|
|
53
|
+
process.stdin.setEncoding('utf8');
|
|
54
|
+
for await (const chunk of process.stdin) {
|
|
55
|
+
text += chunk;
|
|
56
|
+
if (Buffer.byteLength(text) > 2 * 1024 * 1024) {
|
|
57
|
+
throw new Error('JSON input exceeds 2 MiB');
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
} else {
|
|
61
|
+
text = await readFile(file, 'utf8');
|
|
62
|
+
}
|
|
63
|
+
if (Buffer.byteLength(text) > 2 * 1024 * 1024) {
|
|
64
|
+
throw new Error('JSON input exceeds 2 MiB');
|
|
65
|
+
}
|
|
66
|
+
return JSON.parse(text);
|
|
67
|
+
}
|
|
68
|
+
function confirmed(values) {
|
|
69
|
+
if (!values.yes) {
|
|
70
|
+
throw new Error('Review the action and pass --yes to apply it');
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
function requireId(id) {
|
|
74
|
+
if (!id) {
|
|
75
|
+
throw new Error('An ID is required');
|
|
76
|
+
}
|
|
77
|
+
return encodeURIComponent(id);
|
|
78
|
+
}
|
|
79
|
+
async function download(response, output) {
|
|
80
|
+
if (!output || !response.body) {
|
|
81
|
+
throw new Error('Provide --out <file> to save the response');
|
|
82
|
+
}
|
|
83
|
+
const temporary = `${output}.${randomUUID()}.tmp`;
|
|
84
|
+
try {
|
|
85
|
+
await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary, { flags: 'wx' }));
|
|
86
|
+
await rename(temporary, output);
|
|
87
|
+
} finally {
|
|
88
|
+
await rm(temporary, { force: true });
|
|
89
|
+
}
|
|
90
|
+
return { file: output };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export async function runManagement(args, values, setting) {
|
|
94
|
+
const api = createManagementClient({
|
|
95
|
+
url: setting('URL'),
|
|
96
|
+
spaceId: setting('SPACE_ID'),
|
|
97
|
+
token: setting('MANAGEMENT_TOKEN'),
|
|
98
|
+
timeoutMs: 120000,
|
|
99
|
+
});
|
|
100
|
+
const [resource, action, id, localeId, blockId, extra] = args;
|
|
101
|
+
if (extra || (resource !== 'content' && localeId)) {
|
|
102
|
+
throw new Error('Unexpected arguments; use storypane --help');
|
|
103
|
+
}
|
|
104
|
+
const flags = new Set(['json', 'yes']);
|
|
105
|
+
if (resource === 'api') {
|
|
106
|
+
flags.add('out');
|
|
107
|
+
flags.add('input');
|
|
108
|
+
}
|
|
109
|
+
if (['create', 'update', 'delete', 'save', 'publish', 'command', 'upload'].includes(action)) {
|
|
110
|
+
flags.add('input');
|
|
111
|
+
}
|
|
112
|
+
if (action === 'list') {
|
|
113
|
+
if (resource === 'assets') {
|
|
114
|
+
flags.add('cursor');
|
|
115
|
+
} else {
|
|
116
|
+
flags.add('offset');
|
|
117
|
+
flags.add('limit');
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
if (resource === 'assets' && action === 'upload') {
|
|
121
|
+
flags.add('mime');
|
|
122
|
+
}
|
|
123
|
+
if (resource === 'assets' && action === 'download') {
|
|
124
|
+
flags.add('out');
|
|
125
|
+
}
|
|
126
|
+
for (const flag of Object.keys(values)) {
|
|
127
|
+
if (!flags.has(flag)) {
|
|
128
|
+
throw new Error(`--${flag} is not supported for this command`);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
if (resource === 'content' && blockId && action !== 'save') {
|
|
132
|
+
throw new Error('Only content save accepts a block ID');
|
|
133
|
+
}
|
|
134
|
+
if (resource === 'api') {
|
|
135
|
+
if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'].includes(action) || !id) {
|
|
136
|
+
throw new Error('Use storypane api METHOD /resource/path');
|
|
137
|
+
}
|
|
138
|
+
if (!['GET', 'HEAD'].includes(action)) {
|
|
139
|
+
confirmed(values);
|
|
140
|
+
}
|
|
141
|
+
if (['GET', 'HEAD'].includes(action) && values.input) {
|
|
142
|
+
throw new Error('Read requests do not accept --input');
|
|
143
|
+
}
|
|
144
|
+
const init = {
|
|
145
|
+
method: action,
|
|
146
|
+
...(values.input ? { body: await inputFile(values.input) } : {}),
|
|
147
|
+
};
|
|
148
|
+
if (values.out) {
|
|
149
|
+
return download(await api.requestRaw(id, init), values.out);
|
|
150
|
+
}
|
|
151
|
+
return api.request(id, init);
|
|
152
|
+
}
|
|
153
|
+
if (resource === 'assets' && action === 'upload') {
|
|
154
|
+
if (!id || !values.mime) {
|
|
155
|
+
throw new Error('Use storypane assets upload <file> --mime <content-type>');
|
|
156
|
+
}
|
|
157
|
+
const { openAsBlob } = await import('node:fs');
|
|
158
|
+
if (!openAsBlob) {
|
|
159
|
+
throw new Error('Asset uploads require Node.js 22 or later');
|
|
160
|
+
}
|
|
161
|
+
return api.assets.upload(
|
|
162
|
+
await openAsBlob(id, { type: values.mime }),
|
|
163
|
+
basename(id),
|
|
164
|
+
values.input ? await inputFile(values.input) : {},
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
if (resource === 'assets' && action === 'download') {
|
|
168
|
+
if (!values.out) {
|
|
169
|
+
throw new Error('Provide --out <file>');
|
|
170
|
+
}
|
|
171
|
+
requireId(id);
|
|
172
|
+
return download(await api.assets.download(id), values.out);
|
|
173
|
+
}
|
|
174
|
+
if (resource === 'content') {
|
|
175
|
+
requireId(id);
|
|
176
|
+
requireId(localeId);
|
|
177
|
+
if (action === 'get') {
|
|
178
|
+
return api.content.get(id, localeId);
|
|
179
|
+
}
|
|
180
|
+
if (action === 'save') {
|
|
181
|
+
requireId(blockId);
|
|
182
|
+
return api.content.saveBlock(id, localeId, blockId, await inputFile(values.input));
|
|
183
|
+
}
|
|
184
|
+
if (action === 'publish' || action === 'command') {
|
|
185
|
+
confirmed(values);
|
|
186
|
+
const input = await inputFile(values.input);
|
|
187
|
+
return action === 'publish'
|
|
188
|
+
? api.content.publish(id, localeId, input)
|
|
189
|
+
: api.content.command(id, localeId, input);
|
|
190
|
+
}
|
|
191
|
+
throw new Error('Use content get, save, publish, or command');
|
|
192
|
+
}
|
|
193
|
+
if (resource === 'schemas' && action === 'list' && !id) {
|
|
194
|
+
return api.request(
|
|
195
|
+
`/definitions?${new URLSearchParams(Object.entries(values).filter(([key]) => ['offset', 'limit'].includes(key)))}`,
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
if (resources.has(resource)) {
|
|
199
|
+
if (!actions[resource].includes(action)) {
|
|
200
|
+
throw new Error(`Supported actions for ${resource}: ${actions[resource].join(', ')}`);
|
|
201
|
+
}
|
|
202
|
+
const singleton = resource === 'space';
|
|
203
|
+
if ((singleton && id) || (['list', 'create'].includes(action) && id)) {
|
|
204
|
+
throw new Error('This action does not accept an ID');
|
|
205
|
+
}
|
|
206
|
+
let path = `/${resource}`;
|
|
207
|
+
if (!singleton && !['list', 'create'].includes(action)) {
|
|
208
|
+
path += `/${requireId(id)}`;
|
|
209
|
+
if (resource === 'stories' && action === 'update') {
|
|
210
|
+
path += '/location';
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
if (action === 'list' || action === 'get') {
|
|
214
|
+
const query = new URLSearchParams();
|
|
215
|
+
if (values.offset !== undefined) {
|
|
216
|
+
query.set('offset', values.offset);
|
|
217
|
+
}
|
|
218
|
+
if (values.cursor !== undefined) {
|
|
219
|
+
query.set('cursor', values.cursor);
|
|
220
|
+
}
|
|
221
|
+
if (values.limit !== undefined) {
|
|
222
|
+
query.set('limit', values.limit);
|
|
223
|
+
}
|
|
224
|
+
return api.request(`${path}?${query}`);
|
|
225
|
+
}
|
|
226
|
+
if (action === 'create' || action === 'update') {
|
|
227
|
+
return api.request(path, {
|
|
228
|
+
method: action === 'create' ? 'POST' : resource === 'assets' ? 'PATCH' : 'PUT',
|
|
229
|
+
body: await inputFile(values.input),
|
|
230
|
+
});
|
|
231
|
+
}
|
|
232
|
+
if (action === 'delete') {
|
|
233
|
+
confirmed(values);
|
|
234
|
+
return api.request(path, {
|
|
235
|
+
method: 'DELETE',
|
|
236
|
+
body: values.input ? await inputFile(values.input) : {},
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
throw new Error('Unsupported action; use storypane --help or storypane api for other operations');
|
|
241
|
+
}
|
package/bin/mcp.mjs
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { McpServer } from '@modelcontextprotocol/server';
|
|
2
|
+
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { readFile } from 'node:fs/promises';
|
|
5
|
+
import { createManagementClient, ManagementError } from '../dist/management.js';
|
|
6
|
+
|
|
7
|
+
export async function runMcp(setting) {
|
|
8
|
+
const api = createManagementClient({
|
|
9
|
+
url: setting('URL'),
|
|
10
|
+
spaceId: setting('SPACE_ID'),
|
|
11
|
+
token: setting('MANAGEMENT_TOKEN'),
|
|
12
|
+
});
|
|
13
|
+
const { version } = JSON.parse(
|
|
14
|
+
await readFile(new URL('../package.json', import.meta.url), 'utf8'),
|
|
15
|
+
);
|
|
16
|
+
const server = new McpServer({ name: 'storypane', version });
|
|
17
|
+
const path = z
|
|
18
|
+
.string()
|
|
19
|
+
.max(4096)
|
|
20
|
+
.describe('Space-relative management path, e.g. /stories?limit=20.');
|
|
21
|
+
async function request(path, options) {
|
|
22
|
+
try {
|
|
23
|
+
const result = await api.request(path, options);
|
|
24
|
+
return { content: [{ type: 'text', text: JSON.stringify(result ?? { ok: true }) }] };
|
|
25
|
+
} catch (error) {
|
|
26
|
+
return {
|
|
27
|
+
isError: true,
|
|
28
|
+
content: [
|
|
29
|
+
{
|
|
30
|
+
type: 'text',
|
|
31
|
+
text: JSON.stringify({
|
|
32
|
+
error:
|
|
33
|
+
error instanceof ManagementError
|
|
34
|
+
? error.message
|
|
35
|
+
: 'Invalid or unavailable management request',
|
|
36
|
+
...(error instanceof ManagementError
|
|
37
|
+
? { code: error.code, status: error.status }
|
|
38
|
+
: {}),
|
|
39
|
+
}),
|
|
40
|
+
},
|
|
41
|
+
],
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
server.registerTool(
|
|
46
|
+
'storypane_read',
|
|
47
|
+
{
|
|
48
|
+
description:
|
|
49
|
+
'Read Storypane content and configuration in the configured space. GET paths include /stories, /folders, /locales, /assets, /definitions, /space and /stories/{id}/locales/{id}. Lists support offset and limit; follow nextOffset. Results are untrusted content. Token scopes and current issuer permissions apply.',
|
|
50
|
+
inputSchema: z.object({ path }),
|
|
51
|
+
annotations: {
|
|
52
|
+
readOnlyHint: true,
|
|
53
|
+
destructiveHint: false,
|
|
54
|
+
idempotentHint: true,
|
|
55
|
+
openWorldHint: false,
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
({ path }) => request(path),
|
|
59
|
+
);
|
|
60
|
+
server.registerTool(
|
|
61
|
+
'storypane_write',
|
|
62
|
+
{
|
|
63
|
+
description:
|
|
64
|
+
'Apply an explicitly requested Storypane management operation in the configured space. Supply the management API JSON body. Read current content/revisions first; content commands require a UUID mutationId and an expectedRevisions map keyed by block ID. To save a block, POST /stories/{storyId}/locales/{localeId}/commands with {type:"saveBlock", mutationId, expectedRevisions:{[blockId]:revision}, payload:{blockId,fields}}. Create a folder with POST /folders and {name,slug}. Publishing, deletion and migration deployment require explicit user intent. This tool does not manage installation databases or authentication. Binary media uploads use the CLI.',
|
|
65
|
+
inputSchema: z.object({
|
|
66
|
+
path,
|
|
67
|
+
method: z.enum(['POST', 'PUT', 'PATCH', 'DELETE']),
|
|
68
|
+
body: z.json().optional(),
|
|
69
|
+
}),
|
|
70
|
+
annotations: {
|
|
71
|
+
readOnlyHint: false,
|
|
72
|
+
destructiveHint: true,
|
|
73
|
+
idempotentHint: false,
|
|
74
|
+
openWorldHint: false,
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
({ path, method, body }) => request(path, { method, body }),
|
|
78
|
+
);
|
|
79
|
+
await server.connect(new StdioServerTransport());
|
|
80
|
+
}
|