@tryghost/app-sdk 0.0.0-stage → 0.1.0-alpha.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.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ Copyright (c) 2013-2026 Ghost Foundation
2
+
3
+ Permission is hereby granted, free of charge, to any person
4
+ obtaining a copy of this software and associated documentation
5
+ files (the "Software"), to deal in the Software without
6
+ restriction, including without limitation the rights to use,
7
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
8
+ copies of the Software, and to permit persons to whom the
9
+ Software is furnished to do so, subject to the following
10
+ conditions:
11
+
12
+ The above copyright notice and this permission notice shall be
13
+ included in all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
17
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22
+ OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,310 @@
1
- # Temporary Holding Version
1
+ # @tryghost/app-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The SDK apps use to talk to Ghost from inside Admin.
4
+
5
+ An app's page runs in a frame inside Ghost Admin. The SDK connects it to Admin,
6
+ gives it the site, the user and the theme, and lets it call the Admin API, keep
7
+ its route in sync with Admin's URL, and send the publisher elsewhere in Admin.
8
+
9
+ > **Alpha.** CI publishes each change to npm as the next `0.1.0-alpha.N` under
10
+ > the `alpha` tag. Alphas make no compatibility promise.
11
+
12
+ ## Quick start
13
+
14
+ Without a bundler, load the bundle (`dist/app-sdk.js` in the package), a single
15
+ ES module with everything inlined:
16
+
17
+ ```html
18
+ <script type="module">
19
+ import { connect } from './app-sdk.js';
20
+
21
+ const ghost = await connect();
22
+ document.body.dataset.theme = ghost.theme.mode;
23
+ ghost.onThemeChange((theme) => (document.body.dataset.theme = theme.mode));
24
+
25
+ const response = await ghost.fetch('/posts/?limit=5');
26
+ const { posts } = await response.json();
27
+ document.title = `${posts.length} posts`; // Admin shows the title as its own
28
+ </script>
29
+ ```
30
+
31
+ With a bundler, install the package. It includes the types and code it uses
32
+ from Ghost's contracts, so its only dependency is `@quilted/threads`:
33
+
34
+ ```sh
35
+ pnpm add @tryghost/app-sdk@alpha
36
+ ```
37
+
38
+ ```ts
39
+ import { connect, GhostAppError } from '@tryghost/app-sdk';
40
+
41
+ try {
42
+ const ghost = await connect();
43
+ history.pushState(null, '', '/episodes/12'); // or your router's navigate(); Admin's URL follows
44
+ } catch (error) {
45
+ if (error instanceof GhostAppError && error.code === 'not_framed') {
46
+ // Opened outside Admin: show a link to the site's Admin instead.
47
+ }
48
+ }
49
+ ```
50
+
51
+ ## API
52
+
53
+ `connect(options?)` resolves with a `Ghost` once Admin has started the app. Call
54
+ it as soon as the page loads. Every call shares one connection. Load the SDK
55
+ only once per page: if a second copy calls `connect()`, it rejects with
56
+ `duplicate_sdk`. `options.timeout` is how long to wait, in milliseconds (10
57
+ seconds by default).
58
+
59
+ Admin connects each document in the frame only once. After Admin has replied,
60
+ that connection is the only one the page gets. If it fails or its session ends,
61
+ every `connect()` rejects with the error it ended with, until the page reloads.
62
+ A failure before Admin replied, such as `not_framed` or a timeout with no reply,
63
+ can be retried.
64
+
65
+ | `Ghost` | What it is |
66
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
67
+ | `site` | `{ url, title, timezone, locale }` |
68
+ | `user` | `{ id, role }` of the staff user. No name or email. To read those, use `fetch('/users/?filter=id:' + user.id)` (`/users/:id/` isn't allowed), where app scopes will apply. |
69
+ | `theme` | `{ mode, accent_color }` that Admin currently uses. `mode` is `light` or `dark`, never `system`. |
70
+ | `onThemeChange(callback)` | Called with the new theme when the publisher switches. Returns a function that unsubscribes. |
71
+ | `session` | `{ revision }`: the installation's revision when the session started. |
72
+ | `path.current` | The app's route: the path, query and fragment of the page's URL, such as `/episodes/12`, normalised the way Admin stores it (`..` resolved, escaped once). |
73
+ | `onPathChange(callback)` | Called when Admin moves the app: back or forward in Admin, or one of Admin's links. The page's URL is already there and `popstate` has fired; a multi-page app loads it (see below). |
74
+ | `fetch(path, init?)` | Calls the Admin API as the staff user. `path` is relative to the API root (`/posts/?limit=5`), never a URL. Resolves with a real `Response`. |
75
+ | `open(place)` | Sends the publisher to `{ post: { id } }`, `{ page: { id } }`, `{ member: { id } }` or `{ apps: true }`. Rejects with `rejected` if they're already leaving the app. |
76
+ | `connected` | `false` once the session has ended. |
77
+ | `onSessionEnd(callback)` | Called once, with the `session_ended` error, when this document leaves the app session (a reload, form post or link) or the session ends. |
78
+
79
+ `site`, `user`, `session` and `theme` are frozen, so no part of the page can
80
+ change what the rest of it reads.
81
+
82
+ `fetch` takes `method` (any case), `headers` (anything `Headers` accepts) and
83
+ `body`, which is always JSON. Text is sent unchanged and must be JSON; an object
84
+ or array is sent as JSON. Admin labels it as JSON itself. A body on `GET`, a
85
+ binary body and the headers only Admin sets are refused: `cookie`,
86
+ `authorization`, `content-type`, `content-encoding`, `x-ghost-*`, `origin` and
87
+ similar. Any
88
+ status comes back as a `Response`. `fetch` rejects only when Admin refuses to
89
+ make the request.
90
+
91
+ ### Admin API access
92
+
93
+ `fetch` reaches only these routes, grouped by the scope that will allow them once
94
+ apps have their own token. Anything else is refused as `blocked`. `:id` is an
95
+ object ID, 24 lowercase hexadecimal characters; a slug is one path segment.
96
+
97
+ | Scope | Routes |
98
+ | ------------------ | -------------------------------------------------------------------------------------- |
99
+ | `posts:read` | `GET /posts/`, `GET /posts/:id/`, `GET /posts/slug/:slug/`, `GET /search-index/posts/` |
100
+ | `posts:write` | `POST /posts/`, `PUT /posts/:id/`, `DELETE /posts/:id/` |
101
+ | `pages:read` | `GET /pages/`, `GET /pages/:id/`, `GET /pages/slug/:slug/`, `GET /search-index/pages/` |
102
+ | `pages:write` | `POST /pages/`, `PUT /pages/:id/`, `DELETE /pages/:id/` |
103
+ | `tags:read` | `GET /tags/`, `GET /tags/:id/`, `GET /tags/slug/:slug/`, `GET /search-index/tags/` |
104
+ | `tags:write` | `POST /tags/`, `PUT /tags/:id/`, `DELETE /tags/:id/` |
105
+ | `users:read` | `GET /users/` |
106
+ | `tiers:read` | `GET /tiers/` |
107
+ | `newsletters:read` | `GET /newsletters/` |
108
+ | `slugs:read` | `GET /slugs/:type/:name/`, `GET /slugs/:type/:name/:id/` |
109
+
110
+ An app can't ask Ghost to email a post, set a post's code injection or write
111
+ mobiledoc. The one exception: publishing a post that a staff member already
112
+ scheduled with a newsletter sends its email, as it would have at the scheduled
113
+ time.
114
+
115
+ - A write may carry only the query parameters its scope lists: `include`,
116
+ `formats` and `save_revision` for posts and pages, and `include` for tags.
117
+ Any other name is refused, `newsletter`, `email_segment` and `source`
118
+ included, however it's written.
119
+ - `codeinjection_head` and `codeinjection_foot` are refused with any value, even
120
+ `null`, on posts, pages and tags: leave them out of the body.
121
+ - `mobiledoc` must be `null` or left out: it's deprecated and Ghost 7.0 removes
122
+ it. Write `lexical` instead.
123
+ - The SDK and Admin set the body's content type themselves; an app can't set
124
+ `content-type` or `content-encoding`.
125
+
126
+ To edit a post, send `updated_at` and only the fields you change, never the
127
+ object you read: it comes back with `codeinjection_head` and
128
+ `codeinjection_foot` as `null`, which are refused even as `null`.
129
+
130
+ ```ts
131
+ const { posts } = await (await ghost.fetch(`/posts/${id}/`)).json();
132
+ await ghost.fetch(`/posts/${id}/`, {
133
+ method: 'PUT',
134
+ body: { posts: [{ updated_at: posts[0].updated_at, title: 'New title' }] },
135
+ });
136
+ ```
137
+
138
+ The tags you send replace the post's tags. The tags you read come back with
139
+ `codeinjection_head` and `codeinjection_foot` too, so send each as `{ id }`, or
140
+ `{ name }` for a new one:
141
+
142
+ ```ts
143
+ const tags = posts[0].tags.map(({ id }) => ({ id }));
144
+ await ghost.fetch(`/posts/${id}/`, {
145
+ method: 'PUT',
146
+ body: { posts: [{ updated_at: posts[0].updated_at, tags: [...tags, { name: 'Featured' }] }] },
147
+ });
148
+ ```
149
+
150
+ These checks are a stopgap for the private beta. They're reviewed again before
151
+ anyone outside the team gets access, and app scopes replace them.
152
+
153
+ The refusal names the method and path, or what in the request was refused, as
154
+ in `blocked: Apps can't send codeinjection_head to PUT /posts/…/`.
155
+
156
+ ### Routes and history
157
+
158
+ Admin keeps the history, and the app routes as it would anywhere: with
159
+ `history.pushState` and `history.replaceState`, which any router uses, and with
160
+ links. The SDK turns each into a single entry in Admin's history:
161
+
162
+ - `pushState` and a click on a link to the app's own origin add an entry in
163
+ Admin; `replaceState` replaces Admin's current one. The frame itself keeps a
164
+ single entry, so back and forward are always Admin's.
165
+ - A link loads its page in place of the frame's entry, after Admin has recorded
166
+ the move. A link with a `target`, a `download` or a modifier key is left alone,
167
+ and so is one a router has already handled.
168
+ - When the publisher goes back or forward, or Admin moves the app itself, the
169
+ SDK puts the page's URL there, with the state the app last gave that route,
170
+ and dispatches `popstate`, so a router shows it. A multi-page app, with no
171
+ router, loads it: `ghost.onPathChange((path) => location.replace(path))`.
172
+ - Admin opens the app's page at its route, so each route must load directly, as
173
+ with any app that uses browser history. If the page ends up elsewhere, through
174
+ a redirect from its server or a form's result, Admin follows the page.
175
+
176
+ Not intercepted, so each still adds an entry of the frame's own, which back
177
+ steps through without Admin: a form that posts, a change to `location.hash`,
178
+ and the Navigation API. Route with the History API rather than the hash.
179
+
180
+ ### The frame
181
+
182
+ The frame is sandboxed. The page runs scripts and posts forms on its own origin,
183
+ with that origin's storage and cookies, and can open popups and download files.
184
+ It can't navigate Admin's tab, and `alert`, `confirm` and `prompt` return at
185
+ once (`confirm` with `false`), so an app brings its own dialogs. Browser features
186
+ such as the camera, geolocation and fullscreen are off.
187
+
188
+ A popup is sandboxed the same way: it can load any page and `postMessage` back
189
+ to the app, but it can't navigate other windows, Admin's included, or show
190
+ `alert` or `confirm`. To send the publisher somewhere in Admin, use `open`.
191
+
192
+ The SDK reports the page's title automatically. It watches `<title>`, and Admin
193
+ shows the title, up to 200 characters, while the page is open. Characters that
194
+ reorder or hide text, such as direction marks, are removed.
195
+
196
+ ## Errors
197
+
198
+ Every rejection is a `GhostAppError`, whose `code` gives the reason:
199
+
200
+ | `code` | Means |
201
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
202
+ | `not_framed` | The page is not inside a frame, so there is no Admin to talk to. |
203
+ | `not_connected` | Admin did not start the app before the timeout. |
204
+ | `duplicate_sdk` | Another copy of the SDK in the page called `connect()` first, because the page loads the SDK more than once. Load a single copy for the whole page. |
205
+ | `invalid_context` | Admin started the app with a context this SDK cannot read. Updating the SDK usually fixes it. |
206
+ | `session_ended` | The channel to Admin has closed, usually because Admin is reloading the app or the page navigated away from the document. Every call fails after that. |
207
+ | `invalid_argument` | The app passed something that cannot be sent, such as a body on a `GET`. |
208
+ | `invalid_path` | `fetch` was given a URL, a path that leaves the Admin API, or a path the Admin API only redirects, such as `/posts` without its trailing `/`. |
209
+ | `unsupported` | This site's Ghost version predates the call. The message names the call. |
210
+ | `blocked` | A request the allowlist doesn't allow, such as `GET /db/`, or a write that could send email, set code injection or carry mobiledoc (see Admin API access). |
211
+ | `network_error` | Admin could not reach its own API. |
212
+ | `rejected` | Admin refused for another reason; the message says why. |
213
+
214
+ ## How it connects
215
+
216
+ The SDK posts `{ type: 'ghost-app:hello', sdk: <version>, document: <id> }` to
217
+ `window.parent` every 250 ms until Admin replies with `ghost-app:connect`, a
218
+ `MessagePort` and the names of the calls Admin exports. `document` is a random
219
+ ID the SDK makes when it loads. It stays the same for the life of the
220
+ document, so Admin can tell whether a hello comes from a page it has already
221
+ connected or from a new page. The SDK accepts only the first reply, and only
222
+ from the parent window. Over the port, it uses
223
+ [`@quilted/threads`](https://github.com/lemonmade/quilt/tree/main/packages/threads)
224
+ for the calls `@tryghost/app-contracts/bridge` defines, and Admin then calls
225
+ `start`. The SDK refuses a call that the connect message didn't list with
226
+ `unsupported`, without sending it. Admin only ever adds calls, so an older Admin
227
+ lacks the newer ones.
228
+
229
+ Only an error's message survives the channel, so Admin puts the code at the
230
+ start of the message, as in `blocked: Apps can't use GET /db/`. The SDK splits it
231
+ back into `code` and `message`. A message without a known code arrives as
232
+ `rejected`. The SDK refuses Admin's calls the same way: `invalid_context: …` for
233
+ a start context it can't read or a call before the start, and
234
+ `invalid_argument: …` for a theme or path it can't read. The codes and their
235
+ format are defined once, in `@tryghost/app-contracts`.
236
+
237
+ The session ends when the port closes (in browsers that report it, such as
238
+ Chromium), when a message on it can't be read, or when Admin refuses a call with
239
+ `session_ended`. Admin does that to every pending call when it releases the app.
240
+ In other browsers, a page Admin has released is removed along with its frame.
241
+
242
+ When a reload, a form post or a link within the app loads a new document in the
243
+ frame, Admin starts it in place. Admin hides the frame until the new document's
244
+ SDK has connected, then starts it with Admin's current route, so the page shows
245
+ what the form or link loaded, and Admin follows the new document's address. The
246
+ old document's session ends with it. A new document must
247
+ connect within the same 10 seconds, or Admin reloads the app's page. A page that
248
+ keeps reloading or navigating away is shown as not responding: more than five
249
+ documents in a row, each replaced within three seconds of starting. A publisher
250
+ clicking quickly through more than five pages of a multi-page app would trip it
251
+ too.
252
+
253
+ ## Who can frame the page
254
+
255
+ The SDK talks to whichever window frames the page. It can't know a site's Admin
256
+ origin in advance, so if any site can frame the page, any site can fool it: send
257
+ it a start context of its choosing, and answer every `fetch` itself. No Ghost
258
+ credential is ever in the page. But whatever the publisher types into the page
259
+ is exposed, and the app acts on whatever responses it gets.
260
+
261
+ Serve app pages with a `frame-ancestors` Content Security Policy that names the
262
+ Ghost Admin origins of the sites using the app, so nothing else can frame them:
263
+
264
+ ```http
265
+ Content-Security-Policy: frame-ancestors https://site.example
266
+ ```
267
+
268
+ Admin is usually on the site's own origin, or on a separate Admin domain when
269
+ the site has one. An app installed on many sites can build the list from its
270
+ own record of where it is installed.
271
+
272
+ ## Serve only the app from its origin
273
+
274
+ Admin replies to any page on the app's origin that sends a hello from the app's
275
+ frame, and can't tell the app's own pages apart from anything else served there.
276
+ Any such page gets the whole bridge, including `fetch` as the staff user with
277
+ their session. So the origin must serve only the app. Keep user-generated
278
+ content and third-party pages or widgets on another origin (a separate subdomain
279
+ counts). An open redirect is a risk too: a link through it puts another site's
280
+ page in the frame, inside Admin.
281
+
282
+ ## Develop
283
+
284
+ This is a workspace package in the Ghost monorepo. From the package directory:
285
+
286
+ ```bash
287
+ pnpm build # the package to build/ and the browser bundle to dist/, with Vite
288
+ pnpm test # type-check + unit tests (jsdom, with a fake Admin on a real MessageChannel),
289
+ # which build both afresh to check what they import, and pack build/ and dist/
290
+ # to use them from an app outside the workspace (after pnpm build; Nx runs it)
291
+ pnpm lint # lint source and tests
292
+ ```
293
+
294
+ It follows the [internal package golden path](../README.md), except where it
295
+ ships to apps. Its `build` bundles with Vite instead of compiling with `tsc`,
296
+ and also writes `dist/`, which is in `files` and in the Nx build outputs.
297
+
298
+ It uses `@tryghost/app-contracts` for the bridge's message types, limits and
299
+ shape checks, so the SDK and Admin apply the same rules to paths, themes and
300
+ start contexts. It imports only the contracts' root entry point, which doesn't
301
+ load `zod`, and the build inlines what it uses into the SDK, so the contracts
302
+ are a dev dependency:
303
+
304
+ - `build/index.js` imports only `@quilted/threads`;
305
+ - `build/index.d.ts`, emitted by TypeScript 7 and bundled by
306
+ `rolldown-plugin-dts`, imports nothing;
307
+ - `dist/` imports nothing at all.
308
+
309
+ `test/bundle.test.ts` checks this on a fresh build. The build fails if the code
310
+ imports a Node builtin, which Vite would otherwise replace with an empty stub.
@@ -0,0 +1,180 @@
1
+ //#region ../app-contracts/build/bridge/rules.d.ts
2
+ /** Every code a refusal can carry, in either direction. */
3
+ declare const BRIDGE_ERROR_CODES: readonly ["session_ended", "invalid_argument", "invalid_path", "blocked", "network_error", "rejected", "invalid_context"];
4
+ type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[number];
5
+ declare const THEME_MODES: readonly ['light', 'dark'];
6
+ /** The theme Admin is showing, so the page can match it. `mode` is resolved, never `system`. */
7
+ type Theme = {
8
+ mode: (typeof THEME_MODES)[number];
9
+ accent_color: string;
10
+ };
11
+ /**
12
+ * What Admin sends an app's page when the session starts. An older SDK ignores fields a newer
13
+ * Admin adds rather than refusing them, so they don't stop it from starting.
14
+ */
15
+ type StartContext = {
16
+ site: {
17
+ url: string;
18
+ title: string;
19
+ timezone: string;
20
+ locale: string;
21
+ };
22
+ /**
23
+ * Who is using the app, by ID and role only. Name and email are left out on purpose: an
24
+ * app that needs more about a person reads it from the API, through `/users/?filter=id:…`,
25
+ * where app scopes will apply.
26
+ */
27
+ user: {
28
+ id: string;
29
+ role: string;
30
+ };
31
+ theme: Theme;
32
+ /**
33
+ * The installation's revision when this session started. Admin ends the session when the
34
+ * installation's revision changes, so an app never runs against an unapproved revision.
35
+ */
36
+ session: {
37
+ revision: number;
38
+ };
39
+ /**
40
+ * The app's route, taken from Admin's URL, so a reload or a shared link opens the same page:
41
+ * the path, query and fragment of the frame's URL on the app's origin. Admin loads a new
42
+ * frame at it, so it's where the page already is, unless the page's server redirected it.
43
+ */
44
+ path: string;
45
+ };
46
+ /**
47
+ * A place in Admin an app can send the publisher to: a post, a page or a member by its ID, or
48
+ * the apps list.
49
+ */
50
+ type Place = {
51
+ post: {
52
+ id: string;
53
+ };
54
+ } | {
55
+ page: {
56
+ id: string;
57
+ };
58
+ } | {
59
+ member: {
60
+ id: string;
61
+ };
62
+ } | {
63
+ apps: true;
64
+ };
65
+ //#endregion
66
+ //#region src/errors.d.ts
67
+ /**
68
+ * Why an SDK call failed:
69
+ *
70
+ * - `not_framed`: the page is not framed in Admin, so there is nothing to connect to.
71
+ * - `not_connected`: Admin did not start the app in time.
72
+ * - `duplicate_sdk`: another copy of the SDK in the page has already connected, or tried to.
73
+ * - `invalid_context`: Admin started the app with a context this SDK cannot read.
74
+ * - `session_ended`: this document has left the app session, or the session has ended.
75
+ * - `invalid_argument`: the app passed something that cannot be sent.
76
+ * - `invalid_path`: a path that is not an Admin API path, or not a route within the app; or
77
+ * one the Admin API only redirects, such as a path without its trailing `/`.
78
+ * - `unsupported`: this site's version of Ghost doesn't have the call the app made yet. The
79
+ * SDK knows this from the calls Admin listed when it connected.
80
+ * - `blocked`: Admin refused by policy, such as a request the allowlist doesn't allow.
81
+ * - `network_error`: Admin could not reach its own API.
82
+ * - `rejected`: Admin refused for any other reason; the message says why.
83
+ *
84
+ * `not_framed`, `not_connected`, `duplicate_sdk` and `unsupported` are the SDK's own codes; the
85
+ * rest are bridge codes, which cross the channel.
86
+ */
87
+ type GhostAppErrorCode = 'not_framed' | 'not_connected' | 'duplicate_sdk' | 'unsupported' | BridgeErrorCode;
88
+ /** The only error type the SDK rejects with, so an app can branch on `code`. */
89
+ declare class GhostAppError extends Error {
90
+ readonly code: GhostAppErrorCode;
91
+ constructor(code: GhostAppErrorCode, message: string, options?: ErrorOptions);
92
+ }
93
+ //#endregion
94
+ //#region src/types.d.ts
95
+ /** The site the app is running in. */
96
+ type Site = Readonly<StartContext['site']>;
97
+ /**
98
+ * Who is using the app, by ID and role. Read anything more, such as their name, through
99
+ * `ghost.fetch(`/users/?filter=id:${ghost.user.id}`)`: `/users/:id/` isn't allowed.
100
+ */
101
+ type User = Readonly<StartContext['user']>;
102
+ /** The session with Admin: the installation's revision when the session started. */
103
+ type Session = Readonly<StartContext['session']>;
104
+ interface ConnectOptions {
105
+ /** How long to wait for Admin to start the app, in milliseconds. Defaults to 10 seconds. */
106
+ timeout?: number;
107
+ }
108
+ /** A body sent as JSON: a plain object or an array. */
109
+ type JsonBody = Record<string, unknown> | readonly unknown[];
110
+ /** Like `RequestInit`, for the requests Admin can make on the app's behalf. */
111
+ interface GhostFetchInit {
112
+ /** Any case; sent in uppercase. Defaults to `GET`. */
113
+ method?: string;
114
+ headers?: HeadersInit;
115
+ /** Always JSON: text is sent as it is, and an object or array is sent as JSON. */
116
+ body?: string | JsonBody | null;
117
+ }
118
+ /**
119
+ * The app's route, mirrored in Admin's URL. The SDK keeps it in step with the page's own
120
+ * history: the app routes with `history.pushState` and links as it would anywhere, and the SDK
121
+ * reports each move to Admin, which keeps the history.
122
+ */
123
+ interface GhostPath {
124
+ /**
125
+ * The app's route: the path, query and fragment of the page's URL, such as `/episodes/12`, in
126
+ * the URL parser's normalised form, as Admin stores it (`/search?q=a%20b`, `..` resolved).
127
+ */
128
+ readonly current: string;
129
+ }
130
+ type Unsubscribe = () => void;
131
+ /** The connection to Ghost, once Admin has started the app. */
132
+ interface Ghost {
133
+ readonly site: Site;
134
+ readonly user: User;
135
+ /** The theme Admin shows now. `mode` is always `light` or `dark`. */
136
+ readonly theme: Readonly<Theme>;
137
+ readonly session: Session;
138
+ readonly path: GhostPath;
139
+ /** False once the session has ended; every call then rejects with `session_ended`. */
140
+ readonly connected: boolean;
141
+ /** Called when the publisher switches Admin's theme. */
142
+ onThemeChange(callback: (theme: Readonly<Theme>) => void): Unsubscribe;
143
+ /**
144
+ * Called when Admin moves the app to another of its routes: back or forward in Admin's
145
+ * history, or one of Admin's own links. The SDK has already put the page's URL there and
146
+ * dispatched `popstate`, which a router follows. A multi-page app, with no router to render
147
+ * the new address, loads it: `location.replace(path)`. Not called for the app's own moves.
148
+ */
149
+ onPathChange(callback: (path: string) => void): Unsubscribe;
150
+ /**
151
+ * Called once when this document leaves the app session, because the page reloads, posts a
152
+ * form or follows a link, or when the app session itself ends. Called straight away if that
153
+ * has already happened.
154
+ */
155
+ onSessionEnd(callback: (error: GhostAppError) => void): Unsubscribe;
156
+ /**
157
+ * Calls the Admin API as the signed-in staff user. `path` is relative to the Admin API
158
+ * root, such as `/posts/?limit=5`, never a URL. Resolves with a real `Response` whatever
159
+ * its status, and rejects only when Admin refuses to make the request.
160
+ */
161
+ fetch(path: string, init?: GhostFetchInit): Promise<Response>;
162
+ /** Sends the publisher to a place in Admin, such as `{ post: { id } }`. */
163
+ open(place: Place): Promise<void>;
164
+ }
165
+ //#endregion
166
+ //#region src/connect.d.ts
167
+ /**
168
+ * Connects to Ghost Admin, which must frame the page, and resolves once Admin has started the
169
+ * app. Safe to call as soon as the page loads.
170
+ *
171
+ * Every call shares one connection, and the first call's options apply. Only one copy of the
172
+ * SDK in a page can connect; any other copy rejects with `duplicate_sdk`. Admin answers each
173
+ * document only once, so after it answers, that connection is the page's only one. Once it
174
+ * fails or its session ends, every call rejects with the error it ended with, and only a new
175
+ * document (after a reload, for example) can connect again. A failure before Admin answered,
176
+ * such as a bad option or a timeout, can be retried.
177
+ */
178
+ declare function connect(options?: ConnectOptions): Promise<Ghost>;
179
+ //#endregion
180
+ export { type ConnectOptions, type Ghost, GhostAppError, type GhostAppErrorCode, type GhostFetchInit, type GhostPath, type JsonBody, type Place, type Session, type Site, type StartContext, type Theme, type Unsubscribe, type User, connect };