Modernize the Delivery SDK (v17) - #411
Conversation
…tion for simplicity
…ct type check instead of string & type literal
…oves assertion from codename schema utils
…se strict uuid zod schema
…rrowing on content type queries
| const raw = await client.fetchContentItem({ codename: "warrior" }).raw().fetch(); | ||
| ``` | ||
|
|
||
| > v17 does **not** ship a rich-text-to-HTML resolver or portable-text transformer. `element.value` is the |
There was a problem hiding this comment.
link to rich-text resolver
| } | ||
| ``` | ||
|
|
||
| > You don't need to write these by hand — `@kontent-ai/model-generator` emits a type guard |
There was a problem hiding this comment.
link would be nice there as well :D
| ## Installation | ||
|
|
||
| v17 requires Node.js ≥ 22 and has three peer dependencies that were previously bundled: | ||
| `@kontent-ai/core-sdk`, `zod`, and `ts-pattern`. |
There was a problem hiding this comment.
why ts-pattern as peer dep? :D
| @@ -0,0 +1,3 @@ | |||
| { | |||
| "hooks": {} | |||
| } | |||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: pnpm/action-setup@v4 |
There was a problem hiding this comment.
there are newer versions of those checkout i believe. something like v7. check also the other workflows
| expect(params.has("system.language")).toBe(false); | ||
| }); | ||
|
|
||
| it("omits filter with undefined value", () => { |
There was a problem hiding this comment.
nitpick: this is the same test as the one above ("omits undefined filter values" / "omits filter with undefined value") - one can go, or make them check different things :D
| /** | ||
| * Matches the format of the order parameter in the Delivery API. | ||
| * | ||
| * @example |
There was a problem hiding this comment.
nitpick: these @example blocks open ```ts but never close the fence, so they render a bit off in tooltips
| @@ -0,0 +1 @@ | |||
| lts/* No newline at end of file | |||
There was a problem hiding this comment.
.nvmrc is lts/* (floating) while engines says >= 22, and all the workflows read the node version from here - so CI runs on whatever lts happens to be that day. should we pin a concrete major?
| "test": "vitest run --config=vitest.config.ts --coverage", | ||
| "test:unit": "vitest run --config=vitest-unit.config.ts", | ||
| "test:integration": "vitest run --config=vitest-integration.config.ts", | ||
| "test:types": "tsgo -p sample/tsconfig.json", |
There was a problem hiding this comment.
we have a test:types script for the sample/ types but nothing in CI runs it, so the public-api type samples never actually get checked. add a step for it?
| isNotEmptyRichText: "neq", | ||
| }; | ||
|
|
||
| export type ObjectFilter<TSystemProperties extends string, TElementProperties extends string> = { |
There was a problem hiding this comment.
we export Filter / ObjectFilter, but i don't think there's an ergonomic way to type a standalone filter array with them. inline works, as const works, but the moment you write const f: Filter<...>[] = [...] you hand-build the generics - the system-props union has no dedicated export (you'd write keyof ContentItemSystemPayload<DeliveryClientSchema>), and bare string fails because system.${string} is wider than the query wants. the only discoverable options are verbose (NonNullable<ListContentItemsQueryRequest<MySchema>['filters']>, or the keyof ... + AllElementCodenamesOf<MySchema> combo).
could we expose a convenience type like ContentItemFilter<TSchema> that pre-binds system + element props? and maybe a short Filters section in the README - right now it's only in the migration guide :)
2 participants
A ground-up rewrite of the SDK on a modern, functional TypeScript foundation.
Highlights
query, filters })), with renamed, discoverable methods (fetchContentItem, listContentItems,
fetchTaxonomy, …).
success, response, error }, never throw) alongside the throwing variants.
runtime validation of responses.
codename; element codenames are scoped per content type; ContentItemOf + the Elements namespace give
fully-typed item models and type guards.
annotation.
default; use .raw() for a serialization-safe payload.
guards) and a full v16 → v17 migration.md.