@jdevalk/seo-graph-core 0.1.0 → 0.2.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 +7 -28
- package/dist/pieces/organization.d.ts +21 -8
- package/dist/pieces/organization.d.ts.map +1 -1
- package/dist/pieces/organization.js +10 -4
- package/dist/pieces/organization.js.map +1 -1
- package/dist/pieces/webpage.d.ts +7 -2
- package/dist/pieces/webpage.d.ts.map +1 -1
- package/dist/pieces/webpage.js +3 -1
- package/dist/pieces/webpage.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -98,34 +98,13 @@ const graph = assembleGraph([
|
|
|
98
98
|
The [agent-ready web](https://joost.blog/tag/agent-ready/) needs every
|
|
99
99
|
publisher to expose a rich, linked knowledge graph for their content. Hand-
|
|
100
100
|
writing JSON-LD is error-prone; writing it once per framework is worse.
|
|
101
|
-
`@jdevalk/seo-graph-core` is the shared engine behind
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
- [`@jdevalk/astro-seo-graph`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph)
|
|
105
|
-
- [`@jdevalk/emdash-plugin-seo`](https://www.npmjs.com/package/@jdevalk/emdash-plugin-seo)
|
|
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.
|
|
101
|
+
`@jdevalk/seo-graph-core` is the shared engine behind two downstream packages,
|
|
102
|
+
both in production:
|
|
103
|
+
|
|
104
|
+
- [`@jdevalk/astro-seo-graph`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph) — the Astro integration (`<Seo>` + route factories). Used in production by [joost.blog](https://joost.blog) and [limonaia.house](https://limonaia.house).
|
|
105
|
+
- [`@jdevalk/emdash-plugin-seo`](https://www.npmjs.com/package/@jdevalk/emdash-plugin-seo) — the EmDash CMS plugin. Uses `assembleGraph` directly (EmDash contributes metadata through hooks, not through templates, so it doesn't go through the `<Seo>` component).
|
|
106
|
+
|
|
107
|
+
Two different integration runtimes, one graph engine.
|
|
129
108
|
|
|
130
109
|
## License
|
|
131
110
|
|
|
@@ -1,5 +1,6 @@
|
|
|
1
|
+
import type { Organization } from 'schema-dts';
|
|
1
2
|
import type { IdFactory } from '../ids.js';
|
|
2
|
-
export interface OrganizationInput {
|
|
3
|
+
export interface OrganizationInput<T extends Organization = Organization> {
|
|
3
4
|
/** Stable slug used for the @id. */
|
|
4
5
|
slug: string;
|
|
5
6
|
name: string;
|
|
@@ -10,24 +11,36 @@ export interface OrganizationInput {
|
|
|
10
11
|
'@id': string;
|
|
11
12
|
};
|
|
12
13
|
sameAs?: readonly string[];
|
|
13
|
-
/**
|
|
14
|
-
|
|
14
|
+
/**
|
|
15
|
+
* Escape hatch for schema.org properties specific to a subtype. Typed
|
|
16
|
+
* as `Partial<T>` so callers that pass a concrete subtype (e.g.
|
|
17
|
+
* `OrganizationInput<Hotel>`) get schema-dts autocomplete for that
|
|
18
|
+
* subtype's fields — `checkinTime`, `numberOfRooms`, etc. — instead
|
|
19
|
+
* of an untyped `Record<string, unknown>`.
|
|
20
|
+
*/
|
|
21
|
+
extra?: Partial<T>;
|
|
15
22
|
}
|
|
16
23
|
/**
|
|
17
24
|
* Build a schema.org Organization piece, or any of its subtypes. Pass the
|
|
18
|
-
* concrete @type as the third argument
|
|
25
|
+
* concrete @type as the third argument and the matching schema-dts type as
|
|
26
|
+
* the generic parameter to get autocomplete for that subtype's fields:
|
|
19
27
|
*
|
|
20
28
|
* ```ts
|
|
21
29
|
* import type { Hotel } from 'schema-dts';
|
|
22
30
|
* const hotel = buildOrganization<Hotel>(
|
|
23
|
-
* {
|
|
31
|
+
* {
|
|
32
|
+
* slug: 'la-limonaia',
|
|
33
|
+
* name: 'La Limonaia',
|
|
34
|
+
* extra: { checkinTime: '16:00' }, // <-- typed against Hotel
|
|
35
|
+
* },
|
|
24
36
|
* ids,
|
|
25
37
|
* 'Hotel',
|
|
26
38
|
* );
|
|
27
39
|
* ```
|
|
28
40
|
*
|
|
29
|
-
* The generic
|
|
30
|
-
*
|
|
41
|
+
* The generic defaults to `Organization`, so call sites that don't need
|
|
42
|
+
* subtype typing (`buildOrganization({ slug, name }, ids)`) continue to
|
|
43
|
+
* work without specifying `<T>`.
|
|
31
44
|
*/
|
|
32
|
-
export declare function buildOrganization(input: OrganizationInput
|
|
45
|
+
export declare function buildOrganization<T extends Organization = Organization>(input: OrganizationInput<T>, ids: IdFactory, subtype?: string): Record<string, unknown>;
|
|
33
46
|
//# sourceMappingURL=organization.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"organization.d.ts","sourceRoot":"","sources":["../../src/pieces/organization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,iBAAiB;
|
|
1
|
+
{"version":3,"file":"organization.d.ts","sourceRoot":"","sources":["../../src/pieces/organization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACpE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACnE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC3B,GAAG,EAAE,SAAS,EACd,OAAO,GAAE,MAAuB,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB"}
|
|
@@ -1,18 +1,24 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Build a schema.org Organization piece, or any of its subtypes. Pass the
|
|
3
|
-
* concrete @type as the third argument
|
|
3
|
+
* concrete @type as the third argument and the matching schema-dts type as
|
|
4
|
+
* the generic parameter to get autocomplete for that subtype's fields:
|
|
4
5
|
*
|
|
5
6
|
* ```ts
|
|
6
7
|
* import type { Hotel } from 'schema-dts';
|
|
7
8
|
* const hotel = buildOrganization<Hotel>(
|
|
8
|
-
* {
|
|
9
|
+
* {
|
|
10
|
+
* slug: 'la-limonaia',
|
|
11
|
+
* name: 'La Limonaia',
|
|
12
|
+
* extra: { checkinTime: '16:00' }, // <-- typed against Hotel
|
|
13
|
+
* },
|
|
9
14
|
* ids,
|
|
10
15
|
* 'Hotel',
|
|
11
16
|
* );
|
|
12
17
|
* ```
|
|
13
18
|
*
|
|
14
|
-
* The generic
|
|
15
|
-
*
|
|
19
|
+
* The generic defaults to `Organization`, so call sites that don't need
|
|
20
|
+
* subtype typing (`buildOrganization({ slug, name }, ids)`) continue to
|
|
21
|
+
* work without specifying `<T>`.
|
|
16
22
|
*/
|
|
17
23
|
export function buildOrganization(input, ids, subtype = 'Organization') {
|
|
18
24
|
const piece = {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"organization.js","sourceRoot":"","sources":["../../src/pieces/organization.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"organization.js","sourceRoot":"","sources":["../../src/pieces/organization.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC7B,KAA2B,EAC3B,GAAc,EACd,UAAkB,cAAc;IAEhC,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC;QACnC,IAAI,EAAE,KAAK,CAAC,IAAI;KACnB,CAAC;IACF,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACnD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IAC3E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACtD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
|
package/dist/pieces/webpage.d.ts
CHANGED
|
@@ -12,8 +12,13 @@ export interface WebPageInput {
|
|
|
12
12
|
name: string;
|
|
13
13
|
/** Reference to the site-wide WebSite (usually ids.website). */
|
|
14
14
|
isPartOf: Reference;
|
|
15
|
-
/**
|
|
16
|
-
|
|
15
|
+
/**
|
|
16
|
+
* Reference to the BreadcrumbList for this page (usually
|
|
17
|
+
* `ids.breadcrumb(url)`). Optional — schema.org treats `breadcrumb`
|
|
18
|
+
* as optional on `WebPage`, so consumers without breadcrumbs can
|
|
19
|
+
* simply omit it.
|
|
20
|
+
*/
|
|
21
|
+
breadcrumb?: Reference;
|
|
17
22
|
inLanguage?: string;
|
|
18
23
|
/** Publish date — emitted as ISO string. */
|
|
19
24
|
datePublished?: Date;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"webpage.d.ts","sourceRoot":"","sources":["../../src/pieces/webpage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEvE,MAAM,WAAW,YAAY;IACzB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,QAAQ,EAAE,SAAS,CAAC;IACpB
|
|
1
|
+
{"version":3,"file":"webpage.d.ts","sourceRoot":"","sources":["../../src/pieces/webpage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEvE,MAAM,WAAW,YAAY;IACzB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,WAAuB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCzB"}
|
package/dist/pieces/webpage.js
CHANGED
|
@@ -16,10 +16,12 @@ export function buildWebPage(input, ids, type = 'WebPage') {
|
|
|
16
16
|
url: input.url,
|
|
17
17
|
name: input.name,
|
|
18
18
|
isPartOf: input.isPartOf,
|
|
19
|
-
breadcrumb: input.breadcrumb,
|
|
20
19
|
inLanguage: input.inLanguage ?? 'en-US',
|
|
21
20
|
potentialAction,
|
|
22
21
|
};
|
|
22
|
+
if (input.breadcrumb !== undefined) {
|
|
23
|
+
piece.breadcrumb = input.breadcrumb;
|
|
24
|
+
}
|
|
23
25
|
if (input.datePublished !== undefined) {
|
|
24
26
|
piece.datePublished = input.datePublished.toISOString();
|
|
25
27
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"webpage.js","sourceRoot":"","sources":["../../src/pieces/webpage.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"webpage.js","sourceRoot":"","sources":["../../src/pieces/webpage.ts"],"names":[],"mappings":"AA2CA;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CACxB,KAAmB,EACnB,GAAc,EACd,OAAoB,SAAS;IAE7B,MAAM,eAAe,GAA2C,KAAK,CAAC,eAAe,IAAI;QACrF,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;KACjD,CAAC;IAEF,MAAM,KAAK,GAA4B;QACnC,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;QAC7B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,OAAO;QACvC,eAAe;KAClB,CAAC;IAEF,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,WAAW,EAAE,CAAC;IAC5D,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAAC;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC9B,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}
|