@openhi/sdk 0.0.0 → 0.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.
Files changed (90) hide show
  1. package/LICENSE +19 -0
  2. package/README.md +205 -1
  3. package/astro/OpenhiPreview.astro +59 -0
  4. package/lib/api-base.d.ts +2 -0
  5. package/lib/api-base.js +22 -0
  6. package/lib/astro/index.d.ts +8 -0
  7. package/lib/astro/index.js +8 -0
  8. package/lib/astro/loaders.d.ts +131 -0
  9. package/lib/astro/loaders.js +318 -0
  10. package/lib/content/asset.d.ts +69 -0
  11. package/lib/content/asset.js +151 -0
  12. package/lib/content/blocks/catalogue.d.ts +11 -0
  13. package/lib/content/blocks/catalogue.js +71 -0
  14. package/lib/content/blocks/declare.d.ts +143 -0
  15. package/lib/content/blocks/declare.js +210 -0
  16. package/lib/content/blocks/index.d.ts +2 -0
  17. package/lib/content/blocks/index.js +2 -0
  18. package/lib/content/content-type.d.ts +52 -0
  19. package/lib/content/content-type.js +97 -0
  20. package/lib/content/import-plan.d.ts +56 -0
  21. package/lib/content/import-plan.js +71 -0
  22. package/lib/content/index.d.ts +14 -0
  23. package/lib/content/index.js +14 -0
  24. package/lib/content/page.d.ts +91 -0
  25. package/lib/content/page.js +222 -0
  26. package/lib/content/sanitise-html.d.ts +36 -0
  27. package/lib/content/sanitise-html.js +92 -0
  28. package/lib/content/section.d.ts +60 -0
  29. package/lib/content/section.js +59 -0
  30. package/lib/content/shapes.d.ts +68 -0
  31. package/lib/content/shapes.js +9 -0
  32. package/lib/content/theme.d.ts +25 -0
  33. package/lib/content/theme.js +54 -0
  34. package/lib/content/types.d.ts +142 -0
  35. package/lib/content/types.js +121 -0
  36. package/lib/errors.d.ts +25 -0
  37. package/lib/errors.js +25 -0
  38. package/lib/forms/index.d.ts +107 -0
  39. package/lib/forms/index.js +201 -0
  40. package/lib/index.d.ts +10 -0
  41. package/lib/index.js +9 -0
  42. package/lib/node/bin.d.ts +2 -0
  43. package/lib/node/bin.js +14 -0
  44. package/lib/node/cli/api.d.ts +24 -0
  45. package/lib/node/cli/api.js +62 -0
  46. package/lib/node/cli/check.d.ts +26 -0
  47. package/lib/node/cli/check.js +265 -0
  48. package/lib/node/cli/context.d.ts +37 -0
  49. package/lib/node/cli/context.js +55 -0
  50. package/lib/node/cli/env-check.d.ts +4 -0
  51. package/lib/node/cli/env-check.js +47 -0
  52. package/lib/node/cli/init.d.ts +2 -0
  53. package/lib/node/cli/init.js +171 -0
  54. package/lib/node/cli/load-blocks.d.ts +15 -0
  55. package/lib/node/cli/load-blocks.js +109 -0
  56. package/lib/node/cli/local-content.d.ts +47 -0
  57. package/lib/node/cli/local-content.js +126 -0
  58. package/lib/node/cli/main.d.ts +3 -0
  59. package/lib/node/cli/main.js +58 -0
  60. package/lib/node/cli/optional-tool.d.ts +8 -0
  61. package/lib/node/cli/optional-tool.js +26 -0
  62. package/lib/node/cli/pull.d.ts +2 -0
  63. package/lib/node/cli/pull.js +113 -0
  64. package/lib/node/cli/push.d.ts +6 -0
  65. package/lib/node/cli/push.js +227 -0
  66. package/lib/node/env.d.ts +34 -0
  67. package/lib/node/env.js +66 -0
  68. package/lib/node/index.d.ts +9 -0
  69. package/lib/node/index.js +8 -0
  70. package/lib/node/media.d.ts +56 -0
  71. package/lib/node/media.js +176 -0
  72. package/lib/node/read.d.ts +19 -0
  73. package/lib/node/read.js +55 -0
  74. package/lib/paging.d.ts +14 -0
  75. package/lib/paging.js +41 -0
  76. package/lib/preview/apply-draft.d.ts +42 -0
  77. package/lib/preview/apply-draft.js +185 -0
  78. package/lib/preview/index.d.ts +7 -0
  79. package/lib/preview/index.js +4 -0
  80. package/lib/preview/marks.d.ts +25 -0
  81. package/lib/preview/marks.js +17 -0
  82. package/lib/preview/runtime.d.ts +17 -0
  83. package/lib/preview/runtime.js +85 -0
  84. package/lib/preview/studio-origin.d.ts +3 -0
  85. package/lib/preview/studio-origin.js +38 -0
  86. package/lib/transport.d.ts +25 -0
  87. package/lib/transport.js +58 -0
  88. package/lib/trim-slashes.d.ts +4 -0
  89. package/lib/trim-slashes.js +14 -0
  90. package/package.json +124 -3
@@ -0,0 +1,143 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * A site declares its blocks in `openhi.blocks.ts`: the component, its
4
+ * schema and its labels. The block catalogue Studio edits
5
+ * is generated from that file, so Studio and the site cannot disagree about
6
+ * which blocks exist.
7
+ *
8
+ * A block type is a **code**, and the component behind it is the site's
9
+ * own. The catalogue says nothing about components: swapping the component
10
+ * behind a code changes nothing published.
11
+ *
12
+ * ## What is declared, and what is not
13
+ *
14
+ * `fields` names `ContentBlock` members (`title`, `content`, `link`) so a
15
+ * headline ends up where anything reading a page can find it. `props` are
16
+ * the block's own strings, kept in `instance.property`.
17
+ *
18
+ * Repeating content (cards, milestones, slides) is declared as `lists`;
19
+ * enumerated props (`background`, `variant`, `columns`) are deliberately
20
+ * left out. Studio's only editor is a text box: pointed at a closed set it
21
+ * invites a typo that stops the section rendering. A property is declared
22
+ * when a text box is the right editor for it, and anything else is carried
23
+ * through a load and save untouched.
24
+ */
25
+ /** `ContentBlock` members a block can store authored text in. */
26
+ export type BlockField = "title" | "content" | "link";
27
+ /** The names Studio's canvas takes on `instance.property`. */
28
+ export declare const GRID_NAMES: ReadonlySet<string>;
29
+ /**
30
+ * The codes OpenHI's standard catalogue (`CodeSystem/block-type`) owns.
31
+ * A site's own system must not redefine one: the standard would then mean
32
+ * whatever that site last published.
33
+ */
34
+ export declare const STANDARD_BLOCK_CODES: readonly string[];
35
+ export interface BlockListDeclaration {
36
+ readonly name: string;
37
+ /**
38
+ * The text fields of one entry. Empty means a list of plain strings. A
39
+ * field left out is carried through a save untouched but gets no editor.
40
+ */
41
+ readonly fields: readonly string[];
42
+ }
43
+ export interface BlockDeclaration {
44
+ /** Lower-case, because a code is not a class name. */
45
+ readonly code: string;
46
+ /** What Studio calls it. */
47
+ readonly display: string;
48
+ /** One sentence on what the block is for. */
49
+ readonly definition: string;
50
+ /**
51
+ * The component that draws it. Opaque to the kit: it is whatever the
52
+ * site's renderer wants, usually an Astro component, and is read back
53
+ * with `blockComponents()`.
54
+ */
55
+ readonly component?: unknown;
56
+ /**
57
+ * The block's data as a Zod schema (or a JSON Schema). When `fields`,
58
+ * `props` and `lists` are not given they are derived from it: `title`,
59
+ * `content` and `link` become fields, other string properties become
60
+ * props, arrays of strings and of objects become lists.
61
+ */
62
+ readonly schema?: z.ZodType | Record<string, unknown>;
63
+ readonly fields?: readonly BlockField[];
64
+ readonly props?: readonly string[];
65
+ readonly lists?: readonly BlockListDeclaration[];
66
+ /** Grid footprint, `[width, height]`, on Studio's twelve-column canvas. @default [12, 3] */
67
+ readonly size?: readonly [number, number];
68
+ /**
69
+ * Names in the block's data that hold a form's `name`. `openhi-site
70
+ * check` fails when one names a form the site does not have.
71
+ * @default ["form"]
72
+ */
73
+ readonly forms?: readonly string[];
74
+ /**
75
+ * Declared names the build does not draw as text, such as a link's target.
76
+ * Studio edits them; the preview cannot show them, so `openhi-site check`
77
+ * does not ask for a `data-openhi-field` mark on them.
78
+ */
79
+ readonly noPreview?: readonly string[];
80
+ }
81
+ export interface BlockSetDeclaration {
82
+ /** The CodeSystem URL the catalogue is published at: the site's own. */
83
+ readonly system: string;
84
+ /** The CodeSystem `name`. @default derived from the URL */
85
+ readonly name?: string;
86
+ readonly title?: string;
87
+ readonly description?: string;
88
+ readonly version?: string;
89
+ readonly blocks: readonly BlockDeclaration[];
90
+ /**
91
+ * Components for the standard catalogue's codes (`hero`, `cta`, …), by
92
+ * code. Those codes are owned by the standard and are not declared here,
93
+ * but a site still draws them with its own component.
94
+ */
95
+ readonly standard?: Readonly<Record<string, unknown>>;
96
+ }
97
+ /** A block with everything derived, ready to publish. */
98
+ export interface ResolvedBlock {
99
+ readonly code: string;
100
+ readonly display: string;
101
+ readonly definition: string;
102
+ readonly component: unknown;
103
+ readonly fields: readonly BlockField[];
104
+ readonly props: readonly string[];
105
+ readonly lists: readonly BlockListDeclaration[];
106
+ readonly size: readonly [number, number];
107
+ readonly forms: readonly string[];
108
+ readonly noPreview: readonly string[];
109
+ }
110
+ export interface BlockSet {
111
+ readonly system: string;
112
+ readonly name: string;
113
+ readonly title: string;
114
+ readonly description: string;
115
+ readonly version: string;
116
+ readonly blocks: readonly ResolvedBlock[];
117
+ /** The site's components for standard codes, by code. */
118
+ readonly standard: Readonly<Record<string, unknown>>;
119
+ }
120
+ /** The fields, props and lists a data schema says a block has. */
121
+ export declare function deriveFromSchema(schema: z.ZodType | Record<string, unknown>): Pick<ResolvedBlock, "fields" | "props" | "lists">;
122
+ /** What is wrong with a set of declarations, if anything. */
123
+ export declare function blockProblems(set: BlockSetDeclaration | BlockSet): string[];
124
+ /** One declaration with its fields, props and lists settled. */
125
+ export declare function resolveBlock(block: BlockDeclaration): ResolvedBlock;
126
+ /**
127
+ * Declare a site's blocks, in `openhi.blocks.ts`:
128
+ *
129
+ * ```ts
130
+ * export default defineBlocks({
131
+ * system: "https://example.org/fhir/CodeSystem/block-type",
132
+ * blocks: [{ code: "banner", display: "Banner", definition: "…", component: Banner, schema }],
133
+ * });
134
+ * ```
135
+ *
136
+ * Throws on a declaration the catalogue could not carry: a duplicate code,
137
+ * a property that is also a field, a canvas name used as a property.
138
+ */
139
+ export declare function defineBlocks(declaration: BlockSetDeclaration): BlockSet;
140
+ /** Code to display name, for the preview's stand-ins. */
141
+ export declare function blockNames(set: BlockSet): Record<string, string>;
142
+ /** Code to component, for a renderer that maps one to the other. */
143
+ export declare function blockComponents(set: BlockSet): Map<string, unknown>;
@@ -0,0 +1,210 @@
1
+ import { trimTrailingSlashes } from "../../trim-slashes.js";
2
+ import { z } from "zod";
3
+ /** The names Studio's canvas takes on `instance.property`. */
4
+ export const GRID_NAMES = new Set([
5
+ "col",
6
+ "row",
7
+ "w",
8
+ "h",
9
+ ]);
10
+ /**
11
+ * The codes OpenHI's standard catalogue (`CodeSystem/block-type`) owns.
12
+ * A site's own system must not redefine one: the standard would then mean
13
+ * whatever that site last published.
14
+ */
15
+ export const STANDARD_BLOCK_CODES = [
16
+ "hero",
17
+ "card-grid",
18
+ "columns",
19
+ "stats",
20
+ "timeline",
21
+ "faq",
22
+ "bullet-list",
23
+ "quote",
24
+ "prose",
25
+ "cta",
26
+ "newsletter",
27
+ ];
28
+ const MEMBERS = new Set(["title", "content", "link"]);
29
+ function isZod(schema) {
30
+ return typeof schema === "object" && schema !== null && "_zod" in schema;
31
+ }
32
+ /** A Zod 3 schema (`_def` but no `_zod`) would otherwise read as a JSON Schema with no fields. */
33
+ function isJsonSchemaObject(schema) {
34
+ if (typeof schema !== "object" || schema === null)
35
+ return false;
36
+ if ("_def" in schema || "safeParse" in schema)
37
+ return false;
38
+ return true;
39
+ }
40
+ const isText = (schema) => schema?.type === "string" &&
41
+ schema.enum === undefined &&
42
+ schema.const === undefined;
43
+ /** The fields, props and lists a data schema says a block has. */
44
+ export function deriveFromSchema(schema) {
45
+ if (!isZod(schema) && !isJsonSchemaObject(schema)) {
46
+ throw new Error("a block's schema must be a Zod 4 schema or a JSON Schema object; " +
47
+ "Zod 3 schemas (including `z` from astro:content on Astro 5) are not read");
48
+ }
49
+ const json = (isZod(schema)
50
+ ? z.toJSONSchema(schema, { io: "input", unrepresentable: "any" })
51
+ : schema);
52
+ const fields = [];
53
+ const props = [];
54
+ const lists = [];
55
+ for (const [name, property] of Object.entries(json.properties ?? {})) {
56
+ if (GRID_NAMES.has(name))
57
+ continue;
58
+ if (property.type === "array") {
59
+ const item = property.items;
60
+ if (name === "link") {
61
+ fields.push("link");
62
+ }
63
+ else if (isText(item)) {
64
+ lists.push({ name, fields: [] });
65
+ }
66
+ else if (item?.type === "object") {
67
+ lists.push({
68
+ name,
69
+ fields: Object.entries(item.properties ?? {})
70
+ .filter(([, member]) => isText(member))
71
+ .map(([member]) => member),
72
+ });
73
+ }
74
+ continue;
75
+ }
76
+ if (!isText(property))
77
+ continue;
78
+ if (MEMBERS.has(name))
79
+ fields.push(name);
80
+ else
81
+ props.push(name);
82
+ }
83
+ return { fields, props, lists };
84
+ }
85
+ /** What is wrong with a set of declarations, if anything. */
86
+ export function blockProblems(set) {
87
+ const problems = [];
88
+ const seen = new Set();
89
+ const standard = new Set(STANDARD_BLOCK_CODES);
90
+ let url;
91
+ try {
92
+ url = new URL(set.system);
93
+ }
94
+ catch {
95
+ problems.push(`the block system "${set.system}" is not a URL`);
96
+ }
97
+ if (url !== undefined && !/^https?:$/.test(url.protocol)) {
98
+ problems.push(`the block system "${set.system}" is not an http(s) URL`);
99
+ }
100
+ for (const code of Object.keys(set.standard ?? {})) {
101
+ if (!standard.has(code)) {
102
+ problems.push(`standard component "${code}" is not a standard code; declare it in blocks`);
103
+ }
104
+ }
105
+ // Resolving is idempotent, so a set that has been through it is read as it stands.
106
+ const blocks = set.blocks.map((block) => resolveBlock(block));
107
+ for (const block of blocks) {
108
+ const at = `block "${block.code}"`;
109
+ if (block.code.length === 0 || block.code !== block.code.toLowerCase()) {
110
+ problems.push(`${at}: a code is lower-case, because it is not a class name`);
111
+ }
112
+ if (seen.has(block.code))
113
+ problems.push(`${at} is declared twice`);
114
+ seen.add(block.code);
115
+ if (standard.has(block.code)) {
116
+ problems.push(`${at} is a standard code; the standard catalogue owns it`);
117
+ }
118
+ if (new Set(block.props).size !== block.props.length) {
119
+ problems.push(`${at} declares a property twice`);
120
+ }
121
+ for (const field of block.fields) {
122
+ if (block.props.includes(field)) {
123
+ problems.push(`${at}: "${field}" is a field and also a property`);
124
+ }
125
+ }
126
+ for (const name of block.props) {
127
+ if (GRID_NAMES.has(name)) {
128
+ problems.push(`${at}: "${name}" is the canvas's own name; Studio would resize the block`);
129
+ }
130
+ }
131
+ for (const list of block.lists) {
132
+ if (block.props.includes(list.name)) {
133
+ problems.push(`${at}: "${list.name}" is a list and also a property`);
134
+ }
135
+ }
136
+ const [width, height] = block.size;
137
+ if (!Number.isInteger(width) ||
138
+ !Number.isInteger(height) ||
139
+ width < 1 ||
140
+ height < 1) {
141
+ problems.push(`${at}: the size ${width}x${height} cannot be dropped on the canvas`);
142
+ }
143
+ }
144
+ return problems;
145
+ }
146
+ /** One declaration with its fields, props and lists settled. */
147
+ export function resolveBlock(block) {
148
+ const derived = block.schema === undefined ? undefined : deriveFromSchema(block.schema);
149
+ return {
150
+ code: block.code,
151
+ display: block.display,
152
+ definition: block.definition,
153
+ component: block.component,
154
+ fields: block.fields ?? derived?.fields ?? [],
155
+ props: block.props ?? derived?.props ?? [],
156
+ lists: block.lists ?? derived?.lists ?? [],
157
+ size: block.size ?? [12, 3],
158
+ forms: block.forms ?? ["form"],
159
+ noPreview: block.noPreview ?? [],
160
+ };
161
+ }
162
+ function nameFromUrl(system) {
163
+ const last = trimTrailingSlashes(system).split("/").pop() ?? "Blocks";
164
+ return (last
165
+ .split(/[^A-Za-z0-9]+/)
166
+ .filter((part) => part.length > 0)
167
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
168
+ .join("") || "Blocks");
169
+ }
170
+ /**
171
+ * Declare a site's blocks, in `openhi.blocks.ts`:
172
+ *
173
+ * ```ts
174
+ * export default defineBlocks({
175
+ * system: "https://example.org/fhir/CodeSystem/block-type",
176
+ * blocks: [{ code: "banner", display: "Banner", definition: "…", component: Banner, schema }],
177
+ * });
178
+ * ```
179
+ *
180
+ * Throws on a declaration the catalogue could not carry: a duplicate code,
181
+ * a property that is also a field, a canvas name used as a property.
182
+ */
183
+ export function defineBlocks(declaration) {
184
+ const set = {
185
+ system: declaration.system,
186
+ name: declaration.name ?? nameFromUrl(declaration.system),
187
+ title: declaration.title ?? `${nameFromUrl(declaration.system)} blocks`,
188
+ description: declaration.description ??
189
+ "The blocks this site has that the standard catalogue does not. Each concept says what the block takes; the components that render them belong to the site.",
190
+ version: declaration.version ?? "0.0.0",
191
+ blocks: declaration.blocks.map(resolveBlock),
192
+ standard: declaration.standard ?? {},
193
+ };
194
+ const problems = blockProblems(set);
195
+ if (problems.length > 0) {
196
+ throw new Error(`openhi.blocks.ts declares blocks that cannot be published:\n - ${problems.join("\n - ")}`);
197
+ }
198
+ return set;
199
+ }
200
+ /** Code to display name, for the preview's stand-ins. */
201
+ export function blockNames(set) {
202
+ return Object.fromEntries(set.blocks.map((block) => [block.code, block.display]));
203
+ }
204
+ /** Code to component, for a renderer that maps one to the other. */
205
+ export function blockComponents(set) {
206
+ return new Map([
207
+ ...Object.entries(set.standard),
208
+ ...set.blocks.map((block) => [block.code, block.component]),
209
+ ]);
210
+ }
@@ -0,0 +1,2 @@
1
+ export * from "./catalogue.js";
2
+ export * from "./declare.js";
@@ -0,0 +1,2 @@
1
+ export * from "./catalogue.js";
2
+ export * from "./declare.js";
@@ -0,0 +1,52 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * A zod schema as a `ContentDataSchema`.
4
+ *
5
+ * Derived rather than hand-written, so the schema the API validates against
6
+ * and the schema a site validates its own files against cannot drift.
7
+ * Zod emits more than the subset allows, so the surplus is pruned here: a
8
+ * keyword the API would reject is one this would have to be told about
9
+ * twice.
10
+ */
11
+ export declare function toContentDataSchema(schema: z.ZodType): Record<string, unknown>;
12
+ export interface OpenhiContentDefinition {
13
+ readonly resourceType: "ContentDefinition";
14
+ readonly id?: string;
15
+ readonly url: string;
16
+ readonly name: string;
17
+ readonly title: string;
18
+ readonly status: string;
19
+ readonly description?: string;
20
+ readonly dataSchema?: Record<string, unknown>;
21
+ /**
22
+ * Whether entries may be rendered into public output.
23
+ *
24
+ * Absent means no, and it has to be set deliberately.
25
+ */
26
+ readonly publishable?: boolean;
27
+ }
28
+ export interface OpenhiContent {
29
+ readonly resourceType: "Content";
30
+ readonly id?: string;
31
+ readonly definition: {
32
+ readonly reference: string;
33
+ readonly type: "ContentDefinition";
34
+ };
35
+ readonly url?: string;
36
+ readonly status: string;
37
+ readonly title?: string;
38
+ readonly data?: Record<string, unknown>;
39
+ readonly website?: {
40
+ readonly reference?: string;
41
+ readonly type?: string;
42
+ };
43
+ }
44
+ /**
45
+ * One stored `Content` as the data a site's schema parses.
46
+ *
47
+ * The status comes off the resource, not out of `data`. `Content.status`
48
+ * is what Studio sets and what the API indexes; a copy inside `data` is
49
+ * whatever was last written there and can be older. Narrowed the way a
50
+ * page is: anything that is not `active` is not published here.
51
+ */
52
+ export declare function entryFromContent(resource: OpenhiContent): Record<string, unknown>;
@@ -0,0 +1,97 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Tenant-defined content: `ContentDefinition` and `Content`.
4
+ *
5
+ * Used sparingly and on purpose. Pages are `Page`, navigation and the
6
+ * footer are `Section`, files are `ContentAsset` — the content plane has a
7
+ * resource for each and a custom type would be a worse version of it. A
8
+ * tenant-defined type is for what is left: a small relational table, such
9
+ * as a product catalogue or a team roster, that has no place in a block
10
+ * tree. The kit reads these (see `openhiContent()`); declaring and pushing
11
+ * a definition is the site's, since the kit knows no site's content model.
12
+ */
13
+ /**
14
+ * The keywords a `ContentDefinition.dataSchema` may use.
15
+ *
16
+ * It is bounded deliberately: no `$ref`, no `allOf` /
17
+ * `anyOf` / `oneOf` / `not`, no `if` / `then` / `else`, no remote schemas.
18
+ * The envelope schema is `strict()`, so anything outside the subset is
19
+ * rejected at the API rather than stored and failing later.
20
+ */
21
+ const ALLOWED = new Set([
22
+ "$schema",
23
+ "title",
24
+ "description",
25
+ "type",
26
+ "properties",
27
+ "required",
28
+ "additionalProperties",
29
+ "items",
30
+ "enum",
31
+ "const",
32
+ "format",
33
+ "pattern",
34
+ "minimum",
35
+ "maximum",
36
+ "minLength",
37
+ "maxLength",
38
+ "minItems",
39
+ "maxItems",
40
+ "x-fhir-type",
41
+ ]);
42
+ /**
43
+ * A zod schema as a `ContentDataSchema`.
44
+ *
45
+ * Derived rather than hand-written, so the schema the API validates against
46
+ * and the schema a site validates its own files against cannot drift.
47
+ * Zod emits more than the subset allows, so the surplus is pruned here: a
48
+ * keyword the API would reject is one this would have to be told about
49
+ * twice.
50
+ */
51
+ export function toContentDataSchema(schema) {
52
+ const emitted = z.toJSONSchema(schema, {
53
+ // `$ref` is outside the subset, so every shared shape is written out
54
+ // where it is used rather than named once and pointed at.
55
+ io: "input",
56
+ reused: "inline",
57
+ unrepresentable: "any",
58
+ });
59
+ return prune(emitted);
60
+ }
61
+ function prune(value) {
62
+ if (Array.isArray(value))
63
+ return value.map(prune);
64
+ if (typeof value !== "object" || value === null)
65
+ return value;
66
+ const out = {};
67
+ for (const [key, member] of Object.entries(value)) {
68
+ if (!ALLOWED.has(key))
69
+ continue;
70
+ // `properties` is a map of names to schemas, so its keys are data and
71
+ // only its values are pruned.
72
+ if (key === "properties" && typeof member === "object" && member !== null) {
73
+ const properties = {};
74
+ for (const [name, child] of Object.entries(member)) {
75
+ properties[name] = prune(child);
76
+ }
77
+ out[key] = properties;
78
+ continue;
79
+ }
80
+ out[key] = prune(member);
81
+ }
82
+ return out;
83
+ }
84
+ /**
85
+ * One stored `Content` as the data a site's schema parses.
86
+ *
87
+ * The status comes off the resource, not out of `data`. `Content.status`
88
+ * is what Studio sets and what the API indexes; a copy inside `data` is
89
+ * whatever was last written there and can be older. Narrowed the way a
90
+ * page is: anything that is not `active` is not published here.
91
+ */
92
+ export function entryFromContent(resource) {
93
+ return {
94
+ ...(resource.data ?? {}),
95
+ status: resource.status === "active" ? "active" : "inactive",
96
+ };
97
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * What an import would do, decided before anything is written.
3
+ *
4
+ * Separated from the writing so it can be tested without an API and shown
5
+ * before it happens. An importer that reports afterwards is one you have to
6
+ * run to find out what it does.
7
+ */
8
+ /** Anything the importer writes, reduced to what planning needs. */
9
+ export interface Importable {
10
+ readonly resourceType: string;
11
+ readonly id?: string;
12
+ /** What two records at the same address mean: the same thing. */
13
+ readonly url?: string;
14
+ /** Where an asset was imported from, once storing its file moved `url`. */
15
+ readonly identifier?: ReadonlyArray<{
16
+ readonly system?: string;
17
+ readonly value?: string;
18
+ }>;
19
+ }
20
+ export type ImportAction<T extends Importable = Importable> = {
21
+ readonly kind: "create";
22
+ readonly resource: T;
23
+ } | {
24
+ readonly kind: "update";
25
+ readonly resource: T;
26
+ readonly id: string;
27
+ };
28
+ /**
29
+ * Match local records to what is already there, by address.
30
+ *
31
+ * The address is the identity: a page is "the one at /about", not "the one
32
+ * whose file happens to be called about.json". Matching on a file name or a
33
+ * local id would create a second `/about` the moment somebody renamed a
34
+ * file, and the site would then have two records claiming one URL with only
35
+ * one of them reachable.
36
+ *
37
+ * The same holds for a section, a content entry and an asset — each is
38
+ * addressed, so each is matched the same way and the importer stays
39
+ * re-runnable for all of them. An asset whose file has been stored has
40
+ * had its `url` replaced by the file's own address, and keeps the address
41
+ * it came from as an identifier; that is matched too, so the plan says
42
+ * "update" for it rather than announcing a create the server will not do.
43
+ */
44
+ /** The identifier system under which OpenHI keeps an import's source address. */
45
+ export declare const IMPORT_SOURCE_SYSTEM = "https://openhi.org/fhir/identifier/import-source";
46
+ export declare function planImport<T extends Importable>(local: readonly T[], existing: readonly T[]): Array<ImportAction<T>>;
47
+ /** A one-line summary of a plan, for printing before it runs. */
48
+ export declare function describePlan(actions: readonly ImportAction[], noun?: string): string;
49
+ /**
50
+ * What a form keeps from its stored self when git imports it again: every
51
+ * integration git does not define. A payment names a connection that exists
52
+ * only in the workspace, and a Slack integration will too, so
53
+ * those are set in Studio; an integration git does carry (matched by kind)
54
+ * is git's to say.
55
+ */
56
+ export declare function mergeFormIntegrations(local: ReadonlyArray<Record<string, unknown>> | undefined, stored: ReadonlyArray<Record<string, unknown>> | undefined): Array<Record<string, unknown>> | undefined;
@@ -0,0 +1,71 @@
1
+ /**
2
+ * What an import would do, decided before anything is written.
3
+ *
4
+ * Separated from the writing so it can be tested without an API and shown
5
+ * before it happens. An importer that reports afterwards is one you have to
6
+ * run to find out what it does.
7
+ */
8
+ /**
9
+ * Match local records to what is already there, by address.
10
+ *
11
+ * The address is the identity: a page is "the one at /about", not "the one
12
+ * whose file happens to be called about.json". Matching on a file name or a
13
+ * local id would create a second `/about` the moment somebody renamed a
14
+ * file, and the site would then have two records claiming one URL with only
15
+ * one of them reachable.
16
+ *
17
+ * The same holds for a section, a content entry and an asset — each is
18
+ * addressed, so each is matched the same way and the importer stays
19
+ * re-runnable for all of them. An asset whose file has been stored has
20
+ * had its `url` replaced by the file's own address, and keeps the address
21
+ * it came from as an identifier; that is matched too, so the plan says
22
+ * "update" for it rather than announcing a create the server will not do.
23
+ */
24
+ /** The identifier system under which OpenHI keeps an import's source address. */
25
+ export const IMPORT_SOURCE_SYSTEM = "https://openhi.org/fhir/identifier/import-source";
26
+ function sourceOf(resource) {
27
+ return resource.identifier?.find((one) => one.system === IMPORT_SOURCE_SYSTEM)
28
+ ?.value;
29
+ }
30
+ export function planImport(local, existing) {
31
+ const byUrl = new Map();
32
+ const bySource = new Map();
33
+ for (const resource of existing) {
34
+ // First wins, so a duplicate already in the tenant is updated rather
35
+ // than a third being added beside it.
36
+ if (resource.url !== undefined && !byUrl.has(resource.url)) {
37
+ byUrl.set(resource.url, resource);
38
+ }
39
+ const source = sourceOf(resource);
40
+ if (source !== undefined && !bySource.has(source)) {
41
+ bySource.set(source, resource);
42
+ }
43
+ }
44
+ return local.map((resource) => {
45
+ const match = resource.url === undefined
46
+ ? undefined
47
+ : (byUrl.get(resource.url) ?? bySource.get(resource.url));
48
+ return match?.id === undefined
49
+ ? { kind: "create", resource }
50
+ : { kind: "update", resource, id: match.id };
51
+ });
52
+ }
53
+ /** A one-line summary of a plan, for printing before it runs. */
54
+ export function describePlan(actions, noun = "record") {
55
+ const creates = actions.filter((a) => a.kind === "create").length;
56
+ const updates = actions.length - creates;
57
+ return `${actions.length} ${noun}(s): ${creates} to create, ${updates} to update`;
58
+ }
59
+ /**
60
+ * What a form keeps from its stored self when git imports it again: every
61
+ * integration git does not define. A payment names a connection that exists
62
+ * only in the workspace, and a Slack integration will too, so
63
+ * those are set in Studio; an integration git does carry (matched by kind)
64
+ * is git's to say.
65
+ */
66
+ export function mergeFormIntegrations(local, stored) {
67
+ const defined = new Set((local ?? []).map((one) => one.kind));
68
+ const kept = (stored ?? []).filter((one) => !defined.has(one.kind));
69
+ const merged = [...(local ?? []), ...kept];
70
+ return merged.length === 0 ? undefined : merged;
71
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @openhi/sdk/content: content and block helpers with no framework and no
3
+ * Node imports. Maps a site's content files to OpenHI's records and back,
4
+ * declares blocks, and cleans untrusted HTML.
5
+ */
6
+ export * from "./blocks/index.js";
7
+ export * from "./asset.js";
8
+ export * from "./content-type.js";
9
+ export * from "./import-plan.js";
10
+ export * from "./page.js";
11
+ export * from "./section.js";
12
+ export * from "./types.js";
13
+ export { jsonLdScript, sanitiseHtml } from "./sanitise-html.js";
14
+ export * from "./theme.js";
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @openhi/sdk/content: content and block helpers with no framework and no
3
+ * Node imports. Maps a site's content files to OpenHI's records and back,
4
+ * declares blocks, and cleans untrusted HTML.
5
+ */
6
+ export * from "./blocks/index.js";
7
+ export * from "./asset.js";
8
+ export * from "./content-type.js";
9
+ export * from "./import-plan.js";
10
+ export * from "./page.js";
11
+ export * from "./section.js";
12
+ export * from "./types.js";
13
+ export { jsonLdScript, sanitiseHtml } from "./sanitise-html.js";
14
+ export * from "./theme.js";