@kanorio/cli 0.0.0-stage → 1.1.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.
@@ -0,0 +1,396 @@
1
+ /**
2
+ * `kanorio types`: generates TypeScript types from the self-describing schema at `/api/v1/collections` (or the Management API's `/v1/sites/:id/collections`).
3
+ * The output is one file.
4
+ *
5
+ * - `DeliveryAsset` and the `assets` map, one level of `expanded`, and `FieldData`, `Expanded` and `Item` for each collection
6
+ * - Projected fields of system collections (blog `segments`, `toc`, `contentHtml`; taxonomy `counts`) are not hard-coded:
7
+ * they come from `virtualFields` in the `/collections` response (scope `item` goes on the item, `fieldData` goes in the field data)
8
+ * - Response types for `/pages`, `/globals/*`, `/forms/*`, `/redirects` and `/site` are included, so one file covers the whole Delivery API
9
+ */
10
+ function toPascalCase(key) {
11
+ const parts = key
12
+ .replace(/[^a-zA-Z0-9]+/g, " ")
13
+ .trim()
14
+ .split(/\s+/)
15
+ .filter(Boolean);
16
+ const joined = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join("");
17
+ return /^[A-Za-z_]/.test(joined) ? joined : `Collection${joined}`;
18
+ }
19
+ function escapeStringLiteral(val) {
20
+ return JSON.stringify(val);
21
+ }
22
+ function isValidIdent(id) {
23
+ return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id);
24
+ }
25
+ function formatPropertyKey(id) {
26
+ return isValidIdent(id) ? id : escapeStringLiteral(id);
27
+ }
28
+ /** Field type to TS; dates, URLs, emails and the like stay string, with a JSDoc note on the format for IDE hints */
29
+ function fieldTsType(field) {
30
+ // Fields with a fixed shape get their type literal from the server (the system collections' seo)
31
+ if (typeof field.tsType === "string" && field.tsType.trim())
32
+ return { type: field.tsType };
33
+ switch (field.type) {
34
+ case "number":
35
+ return { type: "number" };
36
+ case "boolean":
37
+ return { type: "boolean" };
38
+ case "date":
39
+ return { type: "string", doc: "ISO date `YYYY-MM-DD`" };
40
+ case "datetime":
41
+ return { type: "string", doc: "ISO 8601 datetime (UTC)" };
42
+ case "url":
43
+ return { type: "string", doc: "Absolute URL" };
44
+ case "email":
45
+ return { type: "string", doc: "Email address" };
46
+ case "phone":
47
+ return { type: "string", doc: "Phone number (E.164)" };
48
+ case "image":
49
+ case "file":
50
+ return { type: "string", doc: "assetId — look it up in the top-level `assets` map" };
51
+ case "reference":
52
+ return { type: "string", doc: "Referenced item id — see `expanded` when `?expand=` is used" };
53
+ case "select":
54
+ if (field.options && field.options.length > 0) {
55
+ return { type: field.options.map((o) => escapeStringLiteral(o.id)).join(" | ") };
56
+ }
57
+ return { type: "string" };
58
+ case "multi_select":
59
+ if (field.options && field.options.length > 0) {
60
+ return { type: `Array<${field.options.map((o) => escapeStringLiteral(o.id)).join(" | ")}>` };
61
+ }
62
+ return { type: "string[]" };
63
+ case "gallery":
64
+ return { type: "string[]", doc: "assetIds — look them up in the top-level `assets` map" };
65
+ case "multi_reference":
66
+ return { type: "string[]", doc: "Referenced item ids — see `expanded` when `?expand=` is used" };
67
+ case "json":
68
+ return { type: "Record<string, unknown>" };
69
+ case "rich_text":
70
+ return { type: "string", doc: "Markdown" };
71
+ default:
72
+ return { type: "string" };
73
+ }
74
+ }
75
+ const COMMON_TYPES = `// Generated by \`kanorio types\` — do not edit by hand.
76
+
77
+ export type DeliveryAssetKind = "image" | "video" | "audio" | "pdf" | "document";
78
+
79
+ export interface DeliveryAsset {
80
+ assetId: string;
81
+ url: string;
82
+ width: number | null;
83
+ height: number | null;
84
+ /** Alt written where the image is used, otherwise the asset's default alt text */
85
+ alt: string | null;
86
+ /** Default focal point (0-1 on the original) for object-position or crop gravity; null when unset or centered */
87
+ focus: { x: number; y: number } | null;
88
+ /** url is the watermarked version (or a placeholder while it is being made) */
89
+ watermarked: boolean;
90
+ mimeType: string;
91
+ fileSize: number | null;
92
+ kind: DeliveryAssetKind;
93
+ /** Low-quality image placeholder data URL (16px WebP); null for SVG, animated images and legacy uploads */
94
+ placeholder: string | null;
95
+ }
96
+
97
+ export type DeliveryAssetMap = Record<string, DeliveryAsset>;
98
+
99
+ export interface ExpandedReference<TFieldData = Record<string, unknown>> {
100
+ id: string;
101
+ slug: string;
102
+ title: string;
103
+ fieldData: TFieldData;
104
+ }
105
+
106
+ export interface DeliveryItemEnvelope<TFieldData, TExpanded = Record<string, unknown>> {
107
+ id: string;
108
+ /** URL slug in the locale of the response */
109
+ slug: string;
110
+ /**
111
+ * Path of this item's page on the site, in the locale of the response (\`/blog/hello\`, \`/en/blog/hello\`).
112
+ * The same address Kanorio lists in the sitemap. Absent when the item has no page of its own:
113
+ * a custom collection without \`pathTemplate\`, or a category, tag or author whose listing page is off.
114
+ */
115
+ path?: string;
116
+ publishedAt: string | null;
117
+ updatedAt: string;
118
+ fieldData: TFieldData;
119
+ expanded?: TExpanded;
120
+ /** Multilingual sites: the locale this item was served in (the requested locale when a translation exists, otherwise the primary locale) */
121
+ resolvedLocale?: string;
122
+ /** Multilingual sites: secondary locales that have a published translation of this item */
123
+ availableLocales?: string[];
124
+ /** Multilingual sites: the slug in every live locale */
125
+ localeSlugs?: Record<string, string>;
126
+ /** Multilingual sites, system collections: the path in every live locale (for hreflang and a language switcher) */
127
+ localePaths?: Record<string, string>;
128
+ }
129
+
130
+ export interface DeliveryListResponse<TItem> {
131
+ data: TItem[];
132
+ hasMore: boolean;
133
+ nextCursor: string | null;
134
+ /** Present only when the request asks for it with total=true */
135
+ total?: number;
136
+ assets: DeliveryAssetMap;
137
+ }
138
+
139
+ export interface DeliverySingleResponse<TItem> {
140
+ item: TItem;
141
+ assets: DeliveryAssetMap;
142
+ }
143
+
144
+ export interface DeliveryError {
145
+ error: { code: string; message: string; issues?: unknown };
146
+ }
147
+
148
+ // ---- /site ----
149
+
150
+ export type DeliverySiteBrandLogo = { type: "image"; url: string } | { type: "icon"; icon: string };
151
+
152
+ export interface DeliverySiteBrandColor {
153
+ background: string;
154
+ foreground: string;
155
+ }
156
+
157
+ export interface DeliverySiteBrandFont {
158
+ id: string;
159
+ family: string;
160
+ stylesheetUrl: string | null;
161
+ locales: string[];
162
+ }
163
+
164
+ /** Brand identity from Site settings › Brand: resolved colors, logo, fonts, corner radius and color scheme (same as hosted checkout, sign-in and emails). */
165
+ export interface DeliverySiteBrand {
166
+ displayName: string | null;
167
+ logo: { light: DeliverySiteBrandLogo | null; dark: DeliverySiteBrandLogo | null };
168
+ colors: { primary: { light: DeliverySiteBrandColor; dark: DeliverySiteBrandColor } };
169
+ cornerRadius: "soft" | "normal" | "sharp";
170
+ /** system follows the visitor's device; light or dark fixes Kanorio's hosted checkout, sign-in and customer account */
171
+ colorScheme: "system" | "light" | "dark";
172
+ radius: Record<string, string>;
173
+ typography: {
174
+ bodyEnFontId: string;
175
+ bodyZhHantFontId: string;
176
+ bodyZhHansFontId: string;
177
+ bodyJaFontId: string;
178
+ bodyKoFontId: string;
179
+ };
180
+ fonts: DeliverySiteBrandFont[];
181
+ }
182
+
183
+ export interface DeliverySiteMeta {
184
+ id: string;
185
+ name: string | null;
186
+ description: string | null;
187
+ locale: string | null;
188
+ timezone: string | null;
189
+ currency: string | null;
190
+ frontendMode: "HOSTED" | "HEADLESS";
191
+ homeUrl: string | null;
192
+ publicVersion: string | null;
193
+ brand: DeliverySiteBrand;
194
+ }
195
+
196
+ // ---- /pages ----
197
+
198
+ export interface DeliveryPageSeo {
199
+ seoTitle: string | null;
200
+ seoDescription: string | null;
201
+ seoKeywords: string[];
202
+ ogTitle: string | null;
203
+ ogDescription: string | null;
204
+ ogImage: string | null;
205
+ ogImageAlt: string | null;
206
+ ogImageFraming?: Record<string, unknown> | null;
207
+ canonicalUrl: string | null;
208
+ robotsIndex: string | null;
209
+ robotsFollow: string | null;
210
+ twitterCard: string | null;
211
+ }
212
+
213
+ export interface DeliveryPageSummary {
214
+ id: string;
215
+ slug: string;
216
+ path: string;
217
+ parentSlug: string | null;
218
+ isDirectory: boolean;
219
+ depth: number;
220
+ ancestors: Array<{ slug: string; path: string; title: string }>;
221
+ breadcrumbs: Array<{ label: string; href: string }>;
222
+ breadcrumbSource: "path" | "override";
223
+ title: string;
224
+ pageType: string;
225
+ isHomePage: boolean;
226
+ order: number;
227
+ globalHeaderId: string | null;
228
+ globalFooterId: string | null;
229
+ seo: DeliveryPageSeo;
230
+ publishedAt: string | null;
231
+ updatedAt: string;
232
+ }
233
+
234
+ export interface DeliveryPageDetail extends DeliveryPageSummary {
235
+ /** Published sections, media URLs resolved. Shapes follow the section catalog (GET /v1/sections on the Management API). */
236
+ sections: Array<Record<string, unknown> & { id: string; type: string }>;
237
+ }
238
+
239
+ export interface DeliveryPagesResponse {
240
+ data: DeliveryPageSummary[];
241
+ hasMore: boolean;
242
+ nextCursor: string | null;
243
+ }
244
+
245
+ export interface DeliveryPageResponse {
246
+ page: DeliveryPageDetail;
247
+ assets: DeliveryAssetMap;
248
+ }
249
+
250
+ // ---- /globals ----
251
+
252
+ export interface DeliveryHeaderResponse {
253
+ key: string;
254
+ isPrimary: boolean;
255
+ header: Record<string, unknown> & { id: string; type: "header"; navItems?: unknown[] };
256
+ siteSettings: Record<string, unknown> | null;
257
+ assets: DeliveryAssetMap;
258
+ }
259
+
260
+ export interface DeliveryFooterResponse {
261
+ footer: Record<string, unknown> & { id: string; type: "footer" };
262
+ siteSettings: Record<string, unknown> | null;
263
+ assets: DeliveryAssetMap;
264
+ }
265
+
266
+ // ---- /redirects ----
267
+
268
+ export interface DeliveryRedirect {
269
+ sourcePath: string;
270
+ targetUrl: string;
271
+ statusCode: 301 | 302;
272
+ source: "user" | "system";
273
+ updatedAt: string;
274
+ }
275
+
276
+ export interface DeliveryRedirectsResponse {
277
+ /** The complete list, returned in one response */
278
+ data: DeliveryRedirect[];
279
+ hasMore: false;
280
+ nextCursor: null;
281
+ }
282
+
283
+ // ---- /forms ----
284
+
285
+ export interface DeliveryFormResponse {
286
+ form: Record<string, unknown> & {
287
+ id: string;
288
+ name: string;
289
+ availability: "open" | "closed" | "not_open" | "full";
290
+ fields: Array<Record<string, unknown> & { id: string; type: string; label: string; required?: boolean }>;
291
+ };
292
+ }
293
+
294
+ export interface DeliveryFormChallenge {
295
+ nonce: string;
296
+ ts: number;
297
+ sig: string;
298
+ ttl: number;
299
+ }
300
+
301
+ export interface DeliveryFormSubmitBody {
302
+ answers: Record<string, unknown>;
303
+ consent?: boolean;
304
+ consentTextId?: string;
305
+ locale?: string;
306
+ pagePath?: string;
307
+ _hp?: string;
308
+ _challenge: { nonce: string; ts: number; sig: string };
309
+ }
310
+
311
+ export interface DeliveryFormSubmitResponse {
312
+ ok: true;
313
+ state?: "closed" | "not_open" | "full";
314
+ }
315
+ `;
316
+ export function generateCollectionTypes(collections) {
317
+ const knownByKey = new Map();
318
+ for (const col of collections) {
319
+ knownByKey.set(col.key, toPascalCase(col.key));
320
+ }
321
+ const lines = [COMMON_TYPES, "// ---- /collections ----", ""];
322
+ for (const col of collections) {
323
+ const pascal = knownByKey.get(col.key) ?? toPascalCase(col.key);
324
+ const virtualFieldData = (col.virtualFields ?? []).filter((v) => v.scope === "fieldData");
325
+ const virtualItem = (col.virtualFields ?? []).filter((v) => v.scope === "item");
326
+ const virtualExpanded = (col.virtualFields ?? []).filter((v) => v.scope === "expanded");
327
+ if (col.displayName || col.description) {
328
+ lines.push(`/** ${[col.displayName, col.description].filter(Boolean).join(" — ")} (${col.key}) */`);
329
+ }
330
+ lines.push(`export interface ${pascal}FieldData {`);
331
+ for (const field of col.fields) {
332
+ const prop = formatPropertyKey(field.id);
333
+ const { type, doc } = fieldTsType(field);
334
+ if (doc)
335
+ lines.push(` /** ${doc} */`);
336
+ lines.push(field.required ? ` ${prop}: ${type};` : ` ${prop}?: ${type} | null;`);
337
+ }
338
+ for (const v of virtualFieldData) {
339
+ if (v.description)
340
+ lines.push(` /** ${v.description} */`);
341
+ lines.push(` ${formatPropertyKey(v.id)}?: ${v.tsType};`);
342
+ }
343
+ lines.push("}");
344
+ lines.push("");
345
+ const refFields = col.fields.filter((f) => f.type === "reference" || f.type === "multi_reference");
346
+ lines.push(`export interface ${pascal}Expanded {`);
347
+ for (const rf of refFields) {
348
+ const prop = formatPropertyKey(rf.id);
349
+ const targetPascal = rf.targetCollectionKey ? knownByKey.get(rf.targetCollectionKey) : undefined;
350
+ const targetType = targetPascal ? `${targetPascal}FieldData` : "Record<string, unknown>";
351
+ lines.push(rf.type === "reference" ? ` ${prop}?: ExpandedReference<${targetType}> | null;` : ` ${prop}?: Array<ExpandedReference<${targetType}>>;`);
352
+ }
353
+ const expandedIds = new Set(refFields.map((rf) => rf.id));
354
+ for (const v of virtualExpanded) {
355
+ if (expandedIds.has(v.id))
356
+ continue;
357
+ const targetPascal = v.targetCollectionKey ? knownByKey.get(v.targetCollectionKey) : undefined;
358
+ const targetType = targetPascal ? `${targetPascal}FieldData` : "Record<string, unknown>";
359
+ if (v.description)
360
+ lines.push(` /** ${v.description} */`);
361
+ lines.push(` ${formatPropertyKey(v.id)}?: ExpandedReference<${targetType}> | null;`);
362
+ }
363
+ lines.push("}");
364
+ lines.push("");
365
+ if (virtualItem.length > 0) {
366
+ lines.push(`export interface ${pascal}Item extends DeliveryItemEnvelope<${pascal}FieldData, ${pascal}Expanded> {`);
367
+ for (const v of virtualItem) {
368
+ const doc = [v.description, v.when ? `Present when ${v.when}.` : null].filter(Boolean).join(" ");
369
+ if (doc)
370
+ lines.push(` /** ${doc} */`);
371
+ lines.push(` ${formatPropertyKey(v.id)}?: ${v.tsType};`);
372
+ }
373
+ lines.push("}");
374
+ }
375
+ else {
376
+ lines.push(`export type ${pascal}Item = DeliveryItemEnvelope<${pascal}FieldData, ${pascal}Expanded>;`);
377
+ }
378
+ lines.push("");
379
+ }
380
+ lines.push("export interface KanorioCollectionsMap {");
381
+ for (const col of collections) {
382
+ const pascal = knownByKey.get(col.key) ?? toPascalCase(col.key);
383
+ lines.push(` ${formatPropertyKey(col.key)}: {`);
384
+ lines.push(` fieldData: ${pascal}FieldData;`);
385
+ lines.push(` expanded: ${pascal}Expanded;`);
386
+ lines.push(` item: ${pascal}Item;`);
387
+ lines.push(` list: DeliveryListResponse<${pascal}Item>;`);
388
+ lines.push(` single: DeliverySingleResponse<${pascal}Item>;`);
389
+ lines.push(" };");
390
+ }
391
+ lines.push("}");
392
+ lines.push("");
393
+ lines.push("export type KanorioCollectionKey = keyof KanorioCollectionsMap;");
394
+ lines.push("");
395
+ return lines.join("\n");
396
+ }
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@kanorio/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.1.0",
4
+ "description": "Thin command-line wrapper around the Kanorio Management API (/api/v1), TypeScript codegen (kanorio types), and external frontend doctor (kanorio doctor).",
5
+ "license": "MIT",
6
+ "private": false,
7
+ "publishConfig": {
8
+ "access": "public"
9
+ },
10
+ "homepage": "https://kanorio.com/en/developers/cli",
11
+ "bugs": {
12
+ "email": "support@kanorio.com"
13
+ },
14
+ "keywords": [
15
+ "kanorio",
16
+ "cli",
17
+ "headless",
18
+ "typescript",
19
+ "codegen"
20
+ ],
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/Kanorio-Inc/kanorio.git",
24
+ "directory": "packages/cli"
25
+ },
26
+ "type": "module",
27
+ "bin": {
28
+ "kanorio": "dist/bin.js"
29
+ },
30
+ "files": [
31
+ "dist",
32
+ "README.md",
33
+ "LICENSE"
34
+ ],
35
+ "engines": {
36
+ "node": ">=20"
37
+ },
38
+ "devDependencies": {
39
+ "@types/node": "^20",
40
+ "typescript": "^5",
41
+ "vitest": "^4.1.11"
42
+ },
43
+ "scripts": {
44
+ "build": "tsc -p tsconfig.build.json",
45
+ "typecheck": "tsc --noEmit",
46
+ "test": "vitest run",
47
+ "lint": "echo \"@kanorio/cli: no eslint config yet\""
48
+ }
6
49
  }