schemaorg-kit 1.0.1 → 1.1.1

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 (6) hide show
  1. package/README.md +89 -68
  2. package/dist/index.d.mts +45502 -13617
  3. package/dist/index.d.ts +45502 -13617
  4. package/dist/index.js +1333 -960
  5. package/dist/index.mjs +1317 -960
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## Features
10
10
 
11
- - **35+ factory functions** covering all Google-supported rich result types
11
+ - **40+ factory functions** covering all Google-supported rich result types
12
12
  - **Zod v4 validation** with descriptive error messages at runtime
13
13
  - **Full TypeScript autocomplete** — every field, every enum value
14
14
  - **`@graph` support** for multi-entity pages with cross-references
@@ -27,7 +27,11 @@ Requires **Node.js ≥ 18** and **Zod ≥ 4.3**.
27
27
  ## Quick Start
28
28
 
29
29
  ```typescript
30
- import { createProduct, createOffer, createBreadcrumbList } from "schemaorg-kit";
30
+ import {
31
+ createProduct,
32
+ createOffer,
33
+ createBreadcrumbList,
34
+ } from "schemaorg-kit";
31
35
 
32
36
  const product = createProduct({
33
37
  name: "Running Shoes",
@@ -50,14 +54,14 @@ const jsonLd = product.toJsonLd(); // includes @context
50
54
 
51
55
  Every node returned by a factory exposes these methods:
52
56
 
53
- | Method | Returns | Description |
54
- |--------|---------|-------------|
55
- | `.toObject()` | `T` | Raw validated object — use this when nesting inside another schema |
56
- | `.toJsonLd()` | `Record<string, unknown>` | Object with `@context: "https://schema.org"` added |
57
- | `.toScript()` | `string` | Full `<script type="application/ld+json">` tag, ready for HTML |
58
- | `.toString()` | `string` | Pretty-printed JSON string |
59
- | `.validate()` | `this` | Throws a `ZodError` if data is invalid (chainable) |
60
- | `.safeParse()` | Zod result | Returns `{ success, data, error }` without throwing |
57
+ | Method | Returns | Description |
58
+ | -------------- | ------------------------- | ------------------------------------------------------------------ |
59
+ | `.toObject()` | `T` | Raw validated object — use this when nesting inside another schema |
60
+ | `.toJsonLd()` | `Record<string, unknown>` | Object with `@context: "https://schema.org"` added |
61
+ | `.toScript()` | `string` | Full `<script type="application/ld+json">` tag, ready for HTML |
62
+ | `.toString()` | `string` | Pretty-printed JSON string |
63
+ | `.validate()` | `this` | Throws a `ZodError` if data is invalid (chainable) |
64
+ | `.safeParse()` | Zod result | Returns `{ success, data, error }` without throwing |
61
65
 
62
66
  ## Composing Schemas
63
67
 
@@ -70,7 +74,7 @@ const author = createPerson({ name: "Jane Doe", url: "https://janedoe.com" });
70
74
 
71
75
  const article = createArticle({
72
76
  headline: "Hello World",
73
- author: author.toObject(), // <-- nest with .toObject()
77
+ author: author.toObject(), // <-- nest with .toObject()
74
78
  publisher: createOrganization({
75
79
  name: "Acme Blog",
76
80
  url: "https://acmeblog.com",
@@ -86,10 +90,18 @@ console.log(article.toScript());
86
90
  Use `createGraph` to output multiple schema nodes in a single `<script>` tag with `@id` cross-references:
87
91
 
88
92
  ```typescript
89
- import { createGraph, createWebPage, createArticle, createPerson } from "schemaorg-kit";
93
+ import {
94
+ createGraph,
95
+ createWebPage,
96
+ createArticle,
97
+ createPerson,
98
+ } from "schemaorg-kit";
90
99
 
91
100
  const graph = createGraph([
92
- createWebPage({ "@id": "https://example.com/post#webpage", url: "https://example.com/post" }),
101
+ createWebPage({
102
+ "@id": "https://example.com/post#webpage",
103
+ url: "https://example.com/post",
104
+ }),
93
105
  createArticle({
94
106
  "@id": "https://example.com/post#article",
95
107
  headline: "Hello World",
@@ -110,69 +122,70 @@ As an alternative to named imports, use the `schema()` factory with any register
110
122
  import { schema } from "schemaorg-kit";
111
123
 
112
124
  const product = schema("Product", { name: "Shoes", sku: "SH-001" });
113
- const event = schema("Event", { name: "Conference", startDate: "2025-09-01" });
125
+ const event = schema("Event", { name: "Conference", startDate: "2025-09-01" });
114
126
  ```
115
127
 
116
128
  ## Supported Types
117
129
 
118
130
  ### Things
119
131
 
120
- | Factory | Schema.org Type |
121
- |---------|----------------|
122
- | `createPerson` | `Person` |
123
- | `createOrganization` | `Organization` |
124
- | `createCorporation` | `Corporation` |
125
- | `createNGO` | `NGO` |
126
- | `createOnlineStore` | `OnlineStore` |
132
+ | Factory | Schema.org Type |
133
+ | ---------------------- | ---------------- |
134
+ | `createPerson` | `Person` |
135
+ | `createOrganization` | `Organization` |
136
+ | `createCorporation` | `Corporation` |
137
+ | `createNGO` | `NGO` |
138
+ | `createOnlineStore` | `OnlineStore` |
127
139
  | `createOnlineBusiness` | `OnlineBusiness` |
128
- | `createProduct` | `Product` |
129
- | `createProductGroup` | `ProductGroup` |
130
- | `createEvent` | `Event` |
131
- | `createPlace` | `Place` |
132
- | `createLocalBusiness` | `LocalBusiness` |
133
- | `createRestaurant` | `Restaurant` |
134
- | `createHotel` | `Hotel` |
135
- | `createMovie` | `Movie` |
140
+ | `createProduct` | `Product` |
141
+ | `createProductGroup` | `ProductGroup` |
142
+ | `createEvent` | `Event` |
143
+ | `createPlace` | `Place` |
144
+ | `createLocalBusiness` | `LocalBusiness` |
145
+ | `createRestaurant` | `Restaurant` |
146
+ | `createHotel` | `Hotel` |
147
+ | `createMovie` | `Movie` |
136
148
 
137
149
  ### Creative Works
138
150
 
139
- | Factory | Schema.org Type |
140
- |---------|----------------|
141
- | `createBook` | `Book` (with ReadAction / BorrowAction) |
142
- | `createArticle` | `Article` |
143
- | `createNewsArticle` | `NewsArticle` |
144
- | `createBlogPosting` | `BlogPosting` |
145
- | `createWebPage` | `WebPage` |
146
- | `createWebSite` | `WebSite` |
147
- | `createDataset` | `Dataset` |
148
- | `createRecipe` | `Recipe` |
149
- | `createCourse` | `Course` |
150
- | `createSoftwareApplication` | `SoftwareApplication` |
151
- | `createMobileApplication` | `MobileApplication` |
152
- | `createWebApplication` | `WebApplication` |
153
- | `createMathSolver` | `MathSolver` |
151
+ | Factory | Schema.org Type |
152
+ | --------------------------- | --------------------------------------- |
153
+ | `createBook` | `Book` (with ReadAction / BorrowAction) |
154
+ | `createArticle` | `Article` |
155
+ | `createNewsArticle` | `NewsArticle` |
156
+ | `createBlogPosting` | `BlogPosting` |
157
+ | `createWebPage` | `WebPage` |
158
+ | `createWebSite` | `WebSite` |
159
+ | `createDataset` | `Dataset` |
160
+ | `createRecipe` | `Recipe` |
161
+ | `createCourse` | `Course` |
162
+ | `createSoftwareApplication` | `SoftwareApplication` |
163
+ | `createMobileApplication` | `MobileApplication` |
164
+ | `createWebApplication` | `WebApplication` |
165
+ | `createMathSolver` | `MathSolver` |
166
+ | `createClaimReview` | `ClaimReview` (Fact Check) |
154
167
 
155
168
  ### Intangibles & Other
156
169
 
157
- | Factory | Schema.org Type |
158
- |---------|----------------|
159
- | `createOffer` | `Offer` |
160
- | `createImageObject` | `ImageObject` |
161
- | `createVideoObject` | `VideoObject` |
162
- | `createJobPosting` | `JobPosting` |
163
- | `createQAPage` / `createQuiz` | `QAPage` / `Quiz` |
164
- | `createDiscussionForumPosting` | `DiscussionForumPosting` |
165
- | `createProfilePage` | `ProfilePage` |
166
- | `createVacationRental` | `VacationRental` |
167
- | `createLanguage` | `Language` |
170
+ | Factory | Schema.org Type |
171
+ | ------------------------------------------------ | ------------------------------ |
172
+ | `createOffer` | `Offer` |
173
+ | `createImageObject` | `ImageObject` |
174
+ | `createVideoObject` | `VideoObject` |
175
+ | `createJobPosting` | `JobPosting` |
176
+ | `createQAPage` / `createQuiz` / `createQuestion` | `QAPage` / `Quiz` / `Question` |
177
+ | `createDiscussionForumPosting` | `DiscussionForumPosting` |
178
+ | `createProfilePage` | `ProfilePage` |
179
+ | `createVacationRental` | `VacationRental` |
180
+ | `createLanguage` | `Language` |
168
181
 
169
182
  ### Helpers
170
183
 
171
- | Helper | What it does |
172
- |--------|-------------|
173
- | `createBreadcrumbList([...])` | Builds a `BreadcrumbList` from a plain array |
174
- | `createFAQPage([...])` | Builds a `FAQPage` from `{question, answer}` pairs |
175
- | `createCarousel([...])` | Wraps schema nodes in an `ItemList` carousel |
184
+ | Helper | What it does |
185
+ | ----------------------------- | ------------------------------------------------------------ |
186
+ | `createBreadcrumbList([...])` | Builds a `BreadcrumbList` from a plain array |
187
+ | `createFAQPage([...])` | Builds a `FAQPage` from `{question, answer}` pairs |
188
+ | `createCarousel([...])` | Wraps schema nodes in an `ItemList` carousel |
176
189
  | `createPaywalledArticle(...)` | Article with `isAccessibleForFree: false` paywalled sections |
177
190
 
178
191
  ## Common Patterns
@@ -200,7 +213,9 @@ const product = createProduct({
200
213
  availability: "InStock",
201
214
  shippingDetails: OfferShippingDetailsSchema.parse({
202
215
  shippingRate: { value: 0, currency: "USD" },
203
- shippingDestination: DefinedRegionSchema.parse({ addressCountry: "US" }),
216
+ shippingDestination: DefinedRegionSchema.parse({
217
+ addressCountry: "US",
218
+ }),
204
219
  deliveryTime: {
205
220
  handlingTime: { minValue: 0, maxValue: 1, unitCode: "DAY" },
206
221
  transitTime: { minValue: 3, maxValue: 5, unitCode: "DAY" },
@@ -217,8 +232,11 @@ const product = createProduct({
217
232
  import { createFAQPage } from "schemaorg-kit";
218
233
 
219
234
  const faq = createFAQPage([
220
- { question: "What is schemaorg-kit?", answer: "A type-safe schema.org builder." },
221
- { question: "Does it support @graph?", answer: "Yes, via createGraph()." },
235
+ {
236
+ question: "What is schemaorg-kit?",
237
+ answer: "A type-safe schema.org builder.",
238
+ },
239
+ { question: "Does it support @graph?", answer: "Yes, via createGraph()." },
222
240
  ]);
223
241
 
224
242
  document.head.innerHTML += faq.toScript();
@@ -230,9 +248,9 @@ document.head.innerHTML += faq.toScript();
230
248
  import { createBreadcrumbList } from "schemaorg-kit";
231
249
 
232
250
  const breadcrumb = createBreadcrumbList([
233
- { name: "Home", url: "https://example.com" },
251
+ { name: "Home", url: "https://example.com" },
234
252
  { name: "Products", url: "https://example.com/products" },
235
- { name: "Shoes" }, // last item — url is optional
253
+ { name: "Shoes" }, // last item — url is optional
236
254
  ]);
237
255
  ```
238
256
 
@@ -243,7 +261,7 @@ import { extendThing, makeFactory } from "schemaorg-kit";
243
261
  import { z } from "zod";
244
262
 
245
263
  const PodcastSchema = extendThing("PodcastSeries", {
246
- webFeed: z.string().url(),
264
+ webFeed: z.url(),
247
265
  numberOfEpisodes: z.number().int().optional(),
248
266
  });
249
267
 
@@ -265,10 +283,13 @@ src/
265
283
  │ └── graph.ts # SchemaGraph + createGraph()
266
284
  ├── types/
267
285
  │ ├── shared/ # Reusable building blocks
268
- │ │ ├── Offer.ts # Offer, AggregateOffer, MerchantReturnPolicy
286
+ │ │ ├── Offer.ts # Offer, AggregateOffer, MerchantReturnPolicy, UnitPriceSpecification, ItemCondition
269
287
  │ │ ├── ShippingDetails.ts # OfferShippingDetails, DefinedRegion, ShippingDeliveryTime
270
288
  │ │ ├── Rating.ts # Rating, AggregateRating, Review, EmployerAggregateRating
271
- │ │ ├── VideoObject.ts # VideoObject, Clip, BroadcastEvent
289
+ │ │ ├── VideoObject.ts # VideoObject, Clip, BroadcastEvent, SeekToAction
290
+ │ │ ├── InteractionCounter.ts # InteractionCounter (likes, shares, views)
291
+ │ │ ├── MemberProgram.ts # MemberProgram, MemberProgramTier (loyalty)
292
+ │ │ ├── ShippingService.ts # ShippingService, ShippingConditions, ServicePeriod
272
293
  │ │ └── ...
273
294
  │ ├── things/ # Person, Organization, Product, Place, Event, ...
274
295
  │ ├── creative-works/ # Article, WebPage, WebSite, Recipe, Book, ...