@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,85 @@
1
+ import { pageFromResource } from "../content/page.js";
2
+ import { sanitiseHtml } from "../content/sanitise-html.js";
3
+ import { BLOCK, createDraftPatcher, HIDDEN } from "./apply-draft.js";
4
+ import { isStudioOrigin } from "./studio-origin.js";
5
+ /**
6
+ * A site's side of Studio's preview (openhi `preview/protocol.ts`).
7
+ *
8
+ * Loaded only when the page is opened with `?openhi-preview=1` inside a
9
+ * frame, so a visitor never downloads it. The page announces itself with
10
+ * `openhi:ready`, shows each `openhi:content` draft it is sent, and reports
11
+ * a click on a block with `openhi:select` so Studio can open it.
12
+ */
13
+ const VERSION = 1;
14
+ /**
15
+ * Set on `<html>` by `<OpenhiPreview />` while the page waits for its first
16
+ * draft, so the version it was built with does not flash first. The
17
+ * component also clears it after a moment, in case no draft ever comes.
18
+ */
19
+ export const WAITING = "data-openhi-waiting";
20
+ /** Whether this page was opened by Studio's preview frame. */
21
+ export function isPreviewFrame(window) {
22
+ return (new URLSearchParams(window.location.search).has("openhi-preview") &&
23
+ window.parent !== window);
24
+ }
25
+ export function startPreview(window, options = {}) {
26
+ const { document } = window;
27
+ const root = document.documentElement;
28
+ const reveal = () => root.removeAttribute(WAITING);
29
+ const names = new Map(Object.entries(options.names ?? {}));
30
+ const style = document.createElement("style");
31
+ style.textContent = `
32
+ [${HIDDEN}] { display: none !important; }
33
+ [data-openhi-stand-in] {
34
+ margin: 2rem auto;
35
+ max-width: 1080px;
36
+ padding: 3rem 2rem;
37
+ border: 1px dashed var(--border, #bbb);
38
+ border-radius: var(--radius, 8px);
39
+ color: var(--muted-foreground, #666);
40
+ font-size: 0.875rem;
41
+ text-align: center;
42
+ }
43
+ `;
44
+ document.head.append(style);
45
+ const patcher = createDraftPatcher(document, {
46
+ sanitise: sanitiseHtml,
47
+ nameOf: (code) => names.get(code),
48
+ ...(options.onClone !== undefined && { onClone: options.onClone }),
49
+ });
50
+ // Where Studio is, once it has sent something. Nothing goes back to a
51
+ // parent that has not proved it is Studio.
52
+ let studio;
53
+ window.addEventListener("message", (event) => {
54
+ if (event.source !== window.parent)
55
+ return;
56
+ if (!isStudioOrigin(event.origin, window.location.hostname, options.studioOrigins))
57
+ return;
58
+ const data = event.data;
59
+ if (typeof data !== "object" || data === null)
60
+ return;
61
+ const message = data;
62
+ if (message.type !== "openhi:content")
63
+ return;
64
+ if (typeof message.page !== "object" || message.page === null)
65
+ return;
66
+ studio = event.origin;
67
+ patcher.apply(pageFromResource(message.page).layout);
68
+ reveal();
69
+ });
70
+ // A click opens that block in Studio, and never leaves the page being
71
+ // edited: the next page is chosen in Studio, not by following a link.
72
+ document.addEventListener("click", (event) => {
73
+ const target = event.target;
74
+ if (target?.closest("a[href], button[type=submit]") != null) {
75
+ event.preventDefault();
76
+ }
77
+ const block = target?.closest(`[${BLOCK}]`);
78
+ const id = block?.getAttribute(BLOCK);
79
+ if (studio === undefined || id == null || id.length === 0)
80
+ return;
81
+ window.parent.postMessage({ type: "openhi:select", version: VERSION, instanceId: id }, studio);
82
+ }, true);
83
+ // Carries nothing, so it can go before Studio has shown who it is.
84
+ window.parent.postMessage({ type: "openhi:ready", version: VERSION }, "*");
85
+ }
@@ -0,0 +1,3 @@
1
+ export declare function isStudioOrigin(origin: string, siteHostname: string,
2
+ /** Further origins to trust, exactly as `location.origin` writes them. */
3
+ extra?: readonly string[]): boolean;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Which Studios may send a site a draft.
3
+ *
4
+ * A draft is shown in place of the page's real text, so a frame that would
5
+ * take one from anybody could be made to put any words at all on the site.
6
+ * Only OpenHI's own Studio is trusted: `studio.openhi.org`, each stage's
7
+ * `studio.<stage>.openhi.org`, and a branch preview's
8
+ * `studio-<branch>.<stage>.openhi.org`, all over HTTPS. A stage label
9
+ * never names a hosting zone (`sites`, `apps`, `preview`), because tenants
10
+ * choose names under those and could otherwise claim a Studio host. A Studio running on
11
+ * this machine is trusted only while the site is too, which is how both are
12
+ * worked on together and never how a visitor sees either.
13
+ */
14
+ const RESERVED = "(?!(?:sites|apps|preview|www|api|auth)\\.)";
15
+ const STAGE = `${RESERVED}[a-z0-9-]+`;
16
+ const HOSTED_STUDIO = new RegExp(`^studio(?:\\.${STAGE}|-[a-z0-9-]+\\.${STAGE})?\\.openhi\\.org$`);
17
+ const LOCAL = new Set(["localhost", "127.0.0.1", "[::1]"]);
18
+ export function isStudioOrigin(origin, siteHostname,
19
+ /** Further origins to trust, exactly as `location.origin` writes them. */
20
+ extra = []) {
21
+ if (extra.includes(origin))
22
+ return true;
23
+ let url;
24
+ try {
25
+ url = new URL(origin);
26
+ }
27
+ catch {
28
+ return false;
29
+ }
30
+ if (url.origin !== origin)
31
+ return false;
32
+ if (url.protocol === "https:" && HOSTED_STUDIO.test(url.hostname)) {
33
+ return true;
34
+ }
35
+ return (LOCAL.has(siteHostname) &&
36
+ LOCAL.has(url.hostname) &&
37
+ (url.protocol === "http:" || url.protocol === "https:"));
38
+ }
@@ -0,0 +1,25 @@
1
+ export declare const FHIR_ACCEPT = "application/fhir+json, application/json";
2
+ export interface ClientOptions {
3
+ /** The API's origin, with no path or query. */
4
+ readonly base: string;
5
+ /** The bearer credential sent with every request. Keep it out of browser code. */
6
+ readonly key?: string | undefined;
7
+ /** Defaults to the global `fetch`. */
8
+ readonly fetch?: typeof fetch | undefined;
9
+ }
10
+ export interface OpenhiClient {
11
+ /** The API origin requests go to, without a trailing slash. */
12
+ readonly base: string;
13
+ /**
14
+ * One request. Resolves to the parsed JSON body (`undefined` when there is
15
+ * none) and throws `OpenhiApiError` on a non-2xx answer.
16
+ */
17
+ request(path: string, init?: RequestInit): Promise<unknown>;
18
+ }
19
+ /**
20
+ * A client for the OpenHI API.
21
+ *
22
+ * The credential goes to `base` on every request, so a base that is not an
23
+ * https origin (or local http) is refused here, before any request is made.
24
+ */
25
+ export declare function createClient(options: ClientOptions): OpenhiClient;
@@ -0,0 +1,58 @@
1
+ import { apiBaseProblems } from "./api-base.js";
2
+ import { OpenhiApiError } from "./errors.js";
3
+ import { trimTrailingSlashes } from "./trim-slashes.js";
4
+ export const FHIR_ACCEPT = "application/fhir+json, application/json";
5
+ /**
6
+ * A client for the OpenHI API.
7
+ *
8
+ * The credential goes to `base` on every request, so a base that is not an
9
+ * https origin (or local http) is refused here, before any request is made.
10
+ */
11
+ export function createClient(options) {
12
+ const problems = apiBaseProblems(options.base);
13
+ if (problems.length > 0) {
14
+ throw new Error(`API base cannot be used: ${problems.join("; ")}`);
15
+ }
16
+ const base = trimTrailingSlashes(options.base);
17
+ const send = options.fetch ?? ((...args) => globalThis.fetch(...args));
18
+ return {
19
+ base,
20
+ async request(path, init = {}) {
21
+ const headers = {
22
+ Accept: FHIR_ACCEPT,
23
+ ...(options.key !== undefined && {
24
+ Authorization: `Bearer ${options.key}`,
25
+ }),
26
+ ...(init.body !== undefined && {
27
+ "Content-Type": "application/fhir+json",
28
+ }),
29
+ ...recordOf(init.headers),
30
+ };
31
+ const response = await send(`${base}${path}`, { ...init, headers });
32
+ const text = await response.text();
33
+ let body;
34
+ try {
35
+ body = text.length > 0 ? JSON.parse(text) : undefined;
36
+ }
37
+ catch {
38
+ body = undefined;
39
+ }
40
+ if (!response.ok) {
41
+ const outcome = body;
42
+ throw new OpenhiApiError(init.method ?? "GET", path, response.status, outcome?.issue?.[0]?.diagnostics, body);
43
+ }
44
+ return body;
45
+ },
46
+ };
47
+ }
48
+ /** Request headers given as a plain record or as `Headers`, as one record. */
49
+ function recordOf(headers) {
50
+ if (headers === undefined)
51
+ return {};
52
+ if (Array.isArray(headers))
53
+ return Object.fromEntries(headers);
54
+ if (typeof Headers !== "undefined" && headers instanceof Headers) {
55
+ return Object.fromEntries(headers.entries());
56
+ }
57
+ return headers;
58
+ }
@@ -0,0 +1,4 @@
1
+ /** Drop trailing `/` characters in one linear pass (no regex backtracking). */
2
+ export declare function trimTrailingSlashes(value: string): string;
3
+ /** Drop leading and trailing `/` characters in linear time. */
4
+ export declare function trimSlashes(value: string): string;
@@ -0,0 +1,14 @@
1
+ /** Drop trailing `/` characters in one linear pass (no regex backtracking). */
2
+ export function trimTrailingSlashes(value) {
3
+ let end = value.length;
4
+ while (end > 0 && value.charCodeAt(end - 1) === 47)
5
+ end--;
6
+ return value.slice(0, end);
7
+ }
8
+ /** Drop leading and trailing `/` characters in linear time. */
9
+ export function trimSlashes(value) {
10
+ let start = 0;
11
+ while (start < value.length && value.charCodeAt(start) === 47)
12
+ start++;
13
+ return trimTrailingSlashes(value.slice(start));
14
+ }
package/package.json CHANGED
@@ -1,6 +1,127 @@
1
1
  {
2
2
  "name": "@openhi/sdk",
3
- "version": "0.0.0",
4
- "description": "OpenHI SDK. First real release coming soon.",
5
- "license": "MIT"
3
+ "description": "The OpenHI SDK: a small client core, headless forms, Studio preview, content helpers, Astro loaders and the openhi-site CLI.",
4
+ "bin": {
5
+ "openhi-site": "lib/node/bin.js"
6
+ },
7
+ "scripts": {
8
+ "build": "projen build",
9
+ "bump": "projen bump",
10
+ "bump:next-version": "projen bump:next-version",
11
+ "bump:releasable-commits": "projen bump:releasable-commits",
12
+ "compile": "projen compile",
13
+ "default": "projen default",
14
+ "package": "projen package",
15
+ "post-compile": "projen post-compile",
16
+ "post-upgrade": "projen post-upgrade",
17
+ "pre-compile": "projen pre-compile",
18
+ "release": "projen release",
19
+ "reset": "projen reset",
20
+ "test": "projen test",
21
+ "test:watch": "projen test:watch",
22
+ "type-check": "projen type-check",
23
+ "unbump": "projen unbump",
24
+ "upgrade": "projen upgrade",
25
+ "watch": "projen watch",
26
+ "projen": "projen"
27
+ },
28
+ "devDependencies": {
29
+ "@microsoft/api-extractor": "7.58.7",
30
+ "@types/node": "26.6.6",
31
+ "@types/sanitize-html": "^2.16.2",
32
+ "@vitest/coverage-v8": "5.1.0",
33
+ "astro": "7.4.2",
34
+ "commit-and-tag-version": "^13",
35
+ "esbuild": "^0.28.2",
36
+ "eslint-plugin-jsdoc": "^62.9.0",
37
+ "eslint-plugin-tsdoc": "^0.5.4",
38
+ "jsdom": "^26.1.0",
39
+ "linkedom": "^0.18.15",
40
+ "prettier": "^3.9.10",
41
+ "typescript": "^5.9.3",
42
+ "vitest": "5.1.0"
43
+ },
44
+ "peerDependencies": {
45
+ "astro": ">=6",
46
+ "esbuild": ">=0.25",
47
+ "linkedom": ">=0.18"
48
+ },
49
+ "peerDependenciesMeta": {
50
+ "astro": {
51
+ "optional": true
52
+ },
53
+ "esbuild": {
54
+ "optional": true
55
+ },
56
+ "linkedom": {
57
+ "optional": true
58
+ }
59
+ },
60
+ "dependencies": {
61
+ "sanitize-html": "^2.17.7",
62
+ "zod": "^4"
63
+ },
64
+ "devEngines": {
65
+ "packageManager": {
66
+ "name": "bun",
67
+ "version": "1.4.4",
68
+ "onFail": "ignore"
69
+ }
70
+ },
71
+ "main": "lib/index.js",
72
+ "license": "MIT",
73
+ "publishConfig": {
74
+ "access": "public"
75
+ },
76
+ "version": "0.1.0",
77
+ "types": "lib/index.d.ts",
78
+ "type": "module",
79
+ "sideEffects": [
80
+ "./lib/node/bin.js"
81
+ ],
82
+ "exports": {
83
+ ".": {
84
+ "types": "./lib/index.d.ts",
85
+ "import": "./lib/index.js",
86
+ "default": "./lib/index.js"
87
+ },
88
+ "./forms": {
89
+ "types": "./lib/forms/index.d.ts",
90
+ "import": "./lib/forms/index.js",
91
+ "default": "./lib/forms/index.js"
92
+ },
93
+ "./preview": {
94
+ "types": "./lib/preview/index.d.ts",
95
+ "import": "./lib/preview/index.js",
96
+ "default": "./lib/preview/index.js"
97
+ },
98
+ "./content": {
99
+ "types": "./lib/content/index.d.ts",
100
+ "import": "./lib/content/index.js",
101
+ "default": "./lib/content/index.js"
102
+ },
103
+ "./astro": {
104
+ "types": "./lib/astro/index.d.ts",
105
+ "import": "./lib/astro/index.js",
106
+ "default": "./lib/astro/index.js"
107
+ },
108
+ "./astro/OpenhiPreview.astro": "./astro/OpenhiPreview.astro",
109
+ "./node": {
110
+ "types": "./lib/node/index.d.ts",
111
+ "import": "./lib/node/index.js",
112
+ "default": "./lib/node/index.js"
113
+ },
114
+ "./package.json": "./package.json"
115
+ },
116
+ "files": [
117
+ "lib/**/*.js",
118
+ "lib/**/*.d.ts",
119
+ "!lib/**/*.spec.*",
120
+ "!lib/testing.*",
121
+ "astro/OpenhiPreview.astro",
122
+ "README.md",
123
+ "LICENSE"
124
+ ],
125
+ "packageManager": "bun@1.4.4",
126
+ "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
6
127
  }