@jdevalk/seo-graph-core 0.1.0-alpha.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.
- package/README.md +114 -11
- package/dist/pieces/image.d.ts.map +1 -1
- package/dist/pieces/image.js.map +1 -1
- package/dist/pieces/video.d.ts.map +1 -1
- package/dist/pieces/video.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,27 +2,130 @@
|
|
|
2
2
|
|
|
3
3
|
Pure schema.org JSON-LD graph builders. Runtime-agnostic core for agent-ready SEO.
|
|
4
4
|
|
|
5
|
-
> **Status:** pre-
|
|
6
|
-
>
|
|
5
|
+
> **Status:** `0.1.0` (pre-1.0). The API works and has three real consumers
|
|
6
|
+
> in production, but a few known warts (listed below) will be smoothed out in
|
|
7
|
+
> `0.2.x` without breaking changes before a stable `1.0`.
|
|
7
8
|
|
|
8
9
|
## What this is
|
|
9
10
|
|
|
10
|
-
A small, dependency-light library that builds a valid schema.org `@graph`
|
|
11
|
-
a set of typed inputs. It does one thing: turn structured page data
|
|
12
|
-
byte-correct JSON-LD that search engines and agents can consume.
|
|
11
|
+
A small, dependency-light library that builds a valid schema.org `@graph`
|
|
12
|
+
from a set of typed inputs. It does one thing: turn structured page data
|
|
13
|
+
into byte-correct JSON-LD that search engines and agents can consume.
|
|
13
14
|
|
|
14
|
-
It does **not** know anything about Astro, Next.js, EmDash, WordPress, or
|
|
15
|
-
other runtime. Use `@jdevalk/astro-seo-graph`
|
|
16
|
-
consume this directly from your own CMS
|
|
15
|
+
It does **not** know anything about Astro, Next.js, EmDash, WordPress, or
|
|
16
|
+
any other runtime. Use [`@jdevalk/astro-seo-graph`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph)
|
|
17
|
+
for the Astro integration, or consume this directly from your own CMS or
|
|
18
|
+
framework.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npm install @jdevalk/seo-graph-core
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## What you get
|
|
27
|
+
|
|
28
|
+
| API | Purpose |
|
|
29
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
30
|
+
| `makeIds({ siteUrl, personUrl? })` | `IdFactory` for stable `@id` references across site-wide and per-page entities. |
|
|
31
|
+
| `assembleGraph(pieces)` | Wraps pieces in a `{ @context, @graph }` envelope with first-wins deduplication by `@id`. |
|
|
32
|
+
| `deduplicateByGraphId(entities)` | The dedup engine on its own, in case you need custom assembly. |
|
|
33
|
+
| `buildArticle`, `buildWebPage`, `buildWebSite`, `buildBreadcrumbList`, `buildImageObject`, `buildPerson`, `buildOrganization`, `buildVideoObject`, `buildSiteNavigationElement`, `buildCustomPiece` | Piece builders. All return schema-dts typed objects. |
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import {
|
|
39
|
+
makeIds,
|
|
40
|
+
assembleGraph,
|
|
41
|
+
buildWebSite,
|
|
42
|
+
buildArticle,
|
|
43
|
+
buildWebPage,
|
|
44
|
+
buildBreadcrumbList,
|
|
45
|
+
} from '@jdevalk/seo-graph-core';
|
|
46
|
+
|
|
47
|
+
const ids = makeIds({ siteUrl: 'https://example.com' });
|
|
48
|
+
const url = 'https://example.com/my-post/';
|
|
49
|
+
|
|
50
|
+
const graph = assembleGraph([
|
|
51
|
+
buildWebSite(
|
|
52
|
+
{
|
|
53
|
+
url: 'https://example.com/',
|
|
54
|
+
name: 'Example',
|
|
55
|
+
publisher: { '@id': ids.person },
|
|
56
|
+
},
|
|
57
|
+
ids,
|
|
58
|
+
),
|
|
59
|
+
buildWebPage(
|
|
60
|
+
{
|
|
61
|
+
url,
|
|
62
|
+
name: 'My Post',
|
|
63
|
+
isPartOf: { '@id': ids.website },
|
|
64
|
+
breadcrumb: { '@id': ids.breadcrumb(url) },
|
|
65
|
+
datePublished: new Date('2026-04-07'),
|
|
66
|
+
},
|
|
67
|
+
ids,
|
|
68
|
+
),
|
|
69
|
+
buildArticle(
|
|
70
|
+
{
|
|
71
|
+
url,
|
|
72
|
+
isPartOf: { '@id': ids.webPage(url) },
|
|
73
|
+
author: { '@id': ids.person },
|
|
74
|
+
publisher: { '@id': ids.person },
|
|
75
|
+
headline: 'My Post',
|
|
76
|
+
description: '…',
|
|
77
|
+
datePublished: new Date('2026-04-07'),
|
|
78
|
+
},
|
|
79
|
+
ids,
|
|
80
|
+
),
|
|
81
|
+
buildBreadcrumbList(
|
|
82
|
+
{
|
|
83
|
+
url,
|
|
84
|
+
items: [
|
|
85
|
+
{ name: 'Home', url: 'https://example.com/' },
|
|
86
|
+
{ name: 'My Post', url },
|
|
87
|
+
],
|
|
88
|
+
},
|
|
89
|
+
ids,
|
|
90
|
+
),
|
|
91
|
+
]);
|
|
92
|
+
|
|
93
|
+
// graph === { '@context': 'https://schema.org', '@graph': [...] }
|
|
94
|
+
```
|
|
17
95
|
|
|
18
96
|
## Why
|
|
19
97
|
|
|
20
98
|
The [agent-ready web](https://joost.blog/tag/agent-ready/) needs every
|
|
21
99
|
publisher to expose a rich, linked knowledge graph for their content. Hand-
|
|
22
100
|
writing JSON-LD is error-prone; writing it once per framework is worse.
|
|
23
|
-
`@jdevalk/seo-graph-core` is the shared
|
|
24
|
-
|
|
25
|
-
(
|
|
101
|
+
`@jdevalk/seo-graph-core` is the shared engine behind three real consumers:
|
|
102
|
+
|
|
103
|
+
- [joost.blog](https://joost.blog) (Astro) via a thin local adapter
|
|
104
|
+
- [`@jdevalk/astro-seo-graph`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph) (Astro integration) via `<Seo>` and the route factories
|
|
105
|
+
- [`@jdevalk/emdash-plugin-seo`](https://www.npmjs.com/package/@jdevalk/emdash-plugin-seo) (EmDash CMS plugin) via `assembleGraph`
|
|
106
|
+
|
|
107
|
+
Two different runtimes, one graph engine.
|
|
108
|
+
|
|
109
|
+
## Known limitations
|
|
110
|
+
|
|
111
|
+
The following will be fixed in `0.2.x` without breaking changes. They're
|
|
112
|
+
documented here so you know what's coming.
|
|
113
|
+
|
|
114
|
+
- **`WebPageInput.breadcrumb` is required.** Schema.org treats it as
|
|
115
|
+
optional, and consumers that don't have breadcrumbs can't use
|
|
116
|
+
`buildWebPage` without an `extra` override. Will become optional.
|
|
117
|
+
- **`buildOrganization` takes a `subtype: string` parameter** instead of a
|
|
118
|
+
generic type parameter, which loses schema-dts autocomplete for subtype-
|
|
119
|
+
specific fields like `checkinTime` on a `Hotel`. Will gain a
|
|
120
|
+
`buildOrganization<T extends Organization>(...)` signature.
|
|
121
|
+
- **`makeIds` is hardcoded to joost.blog's `@id` scheme** (`/#/schema.org/WebSite`,
|
|
122
|
+
etc.). Sites with different conventions (like EmDash-style plugins using
|
|
123
|
+
`/#website`) can't use the factory as-is. Will accept custom ID pattern
|
|
124
|
+
overrides.
|
|
125
|
+
|
|
126
|
+
If any of these block you, file an issue at
|
|
127
|
+
https://github.com/jdevalk/seo-graph/issues — the fixes are already in the
|
|
128
|
+
roadmap and prioritization follows real blockers.
|
|
26
129
|
|
|
27
130
|
## License
|
|
28
131
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,
|
|
1
|
+
{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBjG"}
|
package/dist/pieces/image.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,
|
|
1
|
+
{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/pieces/image.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAuB,EAAE,GAAc;IACpE,MAAM,EAAE,GACJ,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5F,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,EAAE;QACT,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,UAAU,EAAE,KAAK,CAAC,GAAG;QACrB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;KACvB,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC/D,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,OAAO,CAAC;IAE/C,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../../src/pieces/video.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,EAAE,SAAS,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,
|
|
1
|
+
{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../../src/pieces/video.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,EAAE,SAAS,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BjG"}
|
package/dist/pieces/video.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"video.js","sourceRoot":"","sources":["../../src/pieces/video.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,MAAM,UAAU,gBAAgB,
|
|
1
|
+
{"version":3,"file":"video.js","sourceRoot":"","sources":["../../src/pieces/video.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAuB,EAAE,GAAc;IACpE,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC;QACjC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;KAC3B,CAAC;IAEF,MAAM,SAAS,GACX,KAAK,CAAC,YAAY;QAClB,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;YAC1B,CAAC,CAAC,8BAA8B,KAAK,CAAC,SAAS,oBAAoB;YACnE,CAAC,CAAC,SAAS,CAAC,CAAC;IACrB,IAAI,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC;IAE5D,MAAM,KAAK,GACP,KAAK,CAAC,QAAQ;QACd,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;YAC1B,CAAC,CAAC,0CAA0C,KAAK,CAAC,SAAS,EAAE;YAC7D,CAAC,CAAC,SAAS,CAAC,CAAC;IACrB,IAAI,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;IAEhD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;IACtF,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAClE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IAExE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
|