@viglet/shio-client 2026.3.2 → 2026.3.3

package/LICENSE

@@ -1,201 +1,201 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,10 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/@viglet/shio-client?logo=npm)](https://www.npmjs.com/package/@viglet/shio-client)
 [![License](https://img.shields.io/npm/l/@viglet/shio-client)](https://github.com/openviglet/shio/blob/HEAD/LICENSE)
-[![Website](https://img.shields.io/badge/shio.viglet.org-0ea5e9?logo=googlechrome&logoColor=white)](https://shio.viglet.org/)
+[![Website](https://img.shields.io/badge/website-0ea5e9?logo=googlechrome&logoColor=white)](https://openviglet.github.io/shio/)
 
 Framework-agnostic **TypeScript client** for the Content Delivery API (CDA) of
-**[Viglet Shio](https://shio.viglet.org/)**, the open source **headless CMS built
+**[Viglet Shio](https://openviglet.github.io/shio/)**, the open source, **agent-ready CMS
 for coding agents**.
 
 - **Zero runtime dependencies** — just `fetch`.
@@ -41,16 +41,41 @@ console.log(post?.attrs.title);
 |---|---|---|
 | `getSites()` | `GET /site` | `ShioSite[]` |
 | `getSite(siteId)` | `GET /site/{id}` | `ShioSite \| null` |
-| `listChildren(folderId, {page,size})` | `GET /object/{id}/list` | `ShioListing \| null` |
+| `listChildren(folderId, {page,size,locale})` | `GET /object/{id}/list` | `ShioListing \| null` |
 | `getPath(objectId)` | `GET /object/{id}/path` | `ShioPath \| null` |
 | `getPost(postId)` | `GET /post/{id}` | `ShioPost \| null` |
-| `getPostByUrl(siteId, url)` | `GET /post/by-url` | `ShioPost \| null` |
-| `query({siteId,folderId,postType,page,size})` | `GET /query` | `ShioListing` |
+| `getPostByUrl(siteId, url, locale?)` | `GET /post/by-url` | `ShioPost \| null` |
+| `query({siteId,folderId,postType,page,size,locale})` | `GET /query` | `ShioListing` |
 
 - Single-resource getters return `null` on `404`.
 - Any other non-OK status throws `ShioHttpError` (`{ status, url, body }`).
 - Every method accepts a final `{ signal }` option for cancellation.
 
+## A language switcher
+
+A site's `locales` says which languages it offers; a post's `availableLocales` says which of
+them this page exists in. Together they are a switcher, with no call beyond the two you
+already make:
+
+```ts
+const site = await shio.getSite(siteId);
+// null when the post at `url` is in another language; its availableLocales say which exist
+const post = await shio.getPostByUrl(siteId, url, locale) ?? await shio.getPostByUrl(siteId, url);
+
+const offered = site?.locales?.enabled ?? [];
+const links = offered.map((tag) => ({
+  tag,
+  // a language this page is missing in shows the site's fallback for it, else its default
+  target: post?.availableLocales.includes(tag)
+    ? tag
+    : site?.locales?.fallback[tag] ?? site?.locales?.defaultLocale,
+}));
+```
+
+`locales.declared` is `false` when nobody has chosen the site's languages yet. The list is
+then the languages its published pages are already written in, which is a description of the
+content so far rather than a promise about it.
+
 ## Next.js App Router — catch-all page
 
 The `getPostByUrl` call is built for `[...slug]` routing:
@@ -115,7 +140,7 @@ npm test           # node:test, no network (injected fetch)
 
 ## License
 
-Apache-2.0 — [Viglet Shio](https://shio.viglet.org/) ·
+Apache-2.0 — [Viglet Shio](https://openviglet.github.io/shio/) ·
 [github.com/openviglet/shio](https://github.com/openviglet/shio) ·
 [docs.viglet.org/shio](https://docs.viglet.org/shio/) ·
 part of the [Viglet](https://www.viglet.org) open source family.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ShioClientConfig, ShioListing, ShioPageParams, ShioPath, ShioPost, ShioPostTypeSchema, ShioQueryParams, ShioRequestOptions, ShioSite } from "./types";
+import type { ShioClientConfig, ShioListing, ShioPageParams, ShioPath, ShioPost, ShioPostTypeSchema, ShioQueryParams, ShioReadOptions, ShioRedirect, ShioRequestOptions, ShioSite } from "./types";
 /**
  * Framework-agnostic client for the Shio Content Delivery API (CDA, SH1).
  *
@@ -22,17 +22,36 @@ export declare class ShioClient {
     getSites(opts?: ShioRequestOptions): Promise<ShioSite[]>;
     /** Get one site (with its root folder id), or `null` if not found. */
     getSite(siteId: string, opts?: ShioRequestOptions): Promise<ShioSite | null>;
+    /**
+     * A site's redirect table (SH1133), ordered by `from`, or `null` if the site is unknown.
+     *
+     * Small and site-scoped, so a front end can hold it and consult it before a 404 rather than
+     * asking per request. A production token sees published redirects only.
+     */
+    getRedirects(siteId: string, opts?: ShioRequestOptions): Promise<ShioRedirect[] | null>;
     /** List a folder's children (subfolders + published posts), or `null` if the folder is unknown. */
     listChildren(folderId: string, params?: ShioPageParams, opts?: ShioRequestOptions): Promise<ShioListing | null>;
     /** Get the breadcrumb path for a folder or post, or `null` if unknown. */
     getPath(objectId: string, opts?: ShioRequestOptions): Promise<ShioPath | null>;
-    /** Get a published post by id (attributes expanded), or `null` if not found / not published. */
-    getPost(postId: string, opts?: ShioRequestOptions): Promise<ShioPost | null>;
+    /**
+     * Get a published post by id (attributes expanded), or `null` if not found / not published.
+     *
+     * SH1081 — `opts.state` asks for another version: `"draft"` or `"rev:<n>"` with a preview token.
+     */
+    getPost(postId: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
     /**
      * Resolve a published post by site + friendly URL — the call behind catch-all
      * routing (e.g. Next.js `[...slug]`). Returns `null` if unresolved.
+     *
+     * SH1057 — pass a `locale` as the third argument to resolve only the translation
+     * in that language: `getPostByUrl(siteId, "/about", "pt-br")` is `null` when the
+     * post at `/about` is in another language, and its `availableLocales` says which.
+     *
+     * SH1081 — `opts.state` asks for another version, as on {@link getPost}: a draft preview of
+     * one page is `getPostByUrl(siteId, "/about", { state: "draft" })` with a preview token.
      */
-    getPostByUrl(siteId: string, url: string, opts?: ShioRequestOptions): Promise<ShioPost | null>;
+    getPostByUrl(siteId: string, url: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
+    getPostByUrl(siteId: string, url: string, locale: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
     /**
      * List every post-type's content-model schema — the input to
      * {@link generateShioTypes}. The schema is global (not site-scoped), so a

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { ShioClient, createShioClient } from "./client";
 export { ShioHttpError } from "./errors";
 export { generateShioTypes } from "./codegen";
 export type { GenerateTypesOptions } from "./codegen";
-export type { ShioClientConfig, ShioRequestOptions, ShioSite, ShioFolder, ShioPostSummary, ShioPost, ShioListing, ShioPath, ShioQueryParams, ShioPageParams, ShioFieldSchema, ShioPostTypeSchema, } from "./types";
+export type { ShioClientConfig, ShioRequestOptions, ShioContentState, ShioReadOptions, ShioSite, ShioSiteLocales, ShioRedirect, ShioFolder, ShioPostSummary, ShioPost, ShioListing, ShioPath, ShioQueryParams, ShioPageParams, ShioFieldSchema, ShioPostTypeSchema, ShioBlock, ShioBlockMark, } from "./types";
+export { SHIO_BLOCK_TYPES, shioBlocks } from "./types";

package/dist/shio-client.js

@@ -1,4 +1,4 @@
-//#region src/errors.ts
+// src/errors.ts
 var e = class e extends Error {
 	constructor(t, n, r) {
 		super(`Shio CDA ${t} for ${n}`), this.name = "ShioHttpError", this.status = t, this.url = n, this.body = r, Object.setPrototypeOf(this, e.prototype);
@@ -20,10 +20,15 @@ var e = class e extends Error {
 	getSite(e, t) {
 		return this.requestOrNull(`/site/${i(e)}`, t);
 	}
+	getRedirects(e, t) {
+		return this.requestOrNull(`/site/${i(e)}/redirects`, t);
+	}
 	listChildren(e, t, n) {
 		let r = a({
 			page: t?.page,
-			size: t?.size
+			size: t?.size,
+			locale: t?.locale,
+			state: t?.state
 		});
 		return this.requestOrNull(`/object/${i(e)}/list${r}`, n);
 	}
@@ -31,14 +36,17 @@ var e = class e extends Error {
 		return this.requestOrNull(`/object/${i(e)}/path`, t);
 	}
 	getPost(e, t) {
-		return this.requestOrNull(`/post/${i(e)}`, t);
+		let n = a({ state: t?.state });
+		return this.requestOrNull(`/post/${i(e)}${n}`, t);
 	}
-	getPostByUrl(e, t, n) {
-		let r = a({
+	getPostByUrl(e, t, n, r) {
+		let i = typeof n == "string" ? n : void 0, o = typeof n == "string" ? r : n, s = a({
 			siteId: e,
-			url: t
+			url: t,
+			locale: i,
+			state: o?.state
 		});
-		return this.requestOrNull(`/post/by-url${r}`, n);
+		return this.requestOrNull(`/post/by-url${s}`, o);
 	}
 	getPostTypes(e) {
 		return this.request("/post-type", e);
@@ -52,7 +60,9 @@ var e = class e extends Error {
 			folderId: e?.folderId,
 			postType: e?.postType,
 			page: e?.page,
-			size: e?.size
+			size: e?.size,
+			locale: e?.locale,
+			state: e?.state
 		});
 		return this.request(`/query${n}`, t);
 	}
@@ -95,8 +105,7 @@ async function o(e) {
 		return;
 	}
 }
-//#endregion
-//#region src/codegen.ts
+// src/codegen.ts
 var s = "@viglet/shio-client", c = "// AUTO-GENERATED by @viglet/shio-client (shio-types). DO NOT EDIT BY HAND.\n// Re-run `shio-types` after changing a post-type.";
 function l(e, t = {}) {
 	let n = t.importFrom ?? s, r = t.banner ?? c, i = [...e].sort((e, t) => e.name.localeCompare(t.name)), a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Set();
@@ -135,5 +144,19 @@ function m(e) {
 	let t = (e ?? "").split(/[^A-Za-z0-9]+/).filter(Boolean).map((e) => e.charAt(0).toUpperCase() + e.slice(1)).join("");
 	return /^[0-9]/.test(t) && (t = `T${t}`), t;
 }
-//#endregion
-export { n as ShioClient, e as ShioHttpError, r as createShioClient, l as generateShioTypes };
+// src/types.ts
+var h = [
+	"heading",
+	"paragraph",
+	"quote",
+	"list",
+	"code",
+	"image",
+	"embed",
+	"reference"
+];
+function g(e, t) {
+	let n = e.attrs?.[t];
+	return Array.isArray(n) ? n : null;
+}
+export { h as SHIO_BLOCK_TYPES, n as ShioClient, e as ShioHttpError, r as createShioClient, l as generateShioTypes, g as shioBlocks };

package/dist/shio-client.umd.cjs

@@ -1,6 +1,6 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.ShioClient={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=class e extends Error{constructor(t,n,r){super(`Shio CDA ${t} for ${n}`),this.name=`ShioHttpError`,this.status=t,this.url=n,this.body=r,Object.setPrototypeOf(this,e.prototype)}},n=`/api/v2/cda`,r=class{constructor(e){if(!e?.baseUrl)throw Error("ShioClient: `baseUrl` is required");this.baseUrl=e.baseUrl.replace(/\/+$/,``),this.headers={Accept:`application/json`,...e.headers??{}},e.apiToken&&(this.headers.Key=e.apiToken);let t=e.fetch??globalThis.fetch;if(typeof t!=`function`)throw Error("ShioClient: no global `fetch` available — pass `fetch` in the config");this.fetchFn=t.bind(globalThis),this.credentials=e.credentials}getSites(e){return this.request(`/site`,e)}getSite(e,t){return this.requestOrNull(`/site/${a(e)}`,t)}listChildren(e,t,n){let r=o({page:t?.page,size:t?.size});return this.requestOrNull(`/object/${a(e)}/list${r}`,n)}getPath(e,t){return this.requestOrNull(`/object/${a(e)}/path`,t)}getPost(e,t){return this.requestOrNull(`/post/${a(e)}`,t)}getPostByUrl(e,t,n){let r=o({siteId:e,url:t});return this.requestOrNull(`/post/by-url${r}`,n)}getPostTypes(e){return this.request(`/post-type`,e)}getPostType(e,t){return this.requestOrNull(`/post-type/${a(e)}`,t)}query(e,t){let n=o({siteId:e?.siteId,folderId:e?.folderId,postType:e?.postType,page:e?.page,size:e?.size});return this.request(`/query${n}`,t)}async send(e,t){return this.fetchFn(`${this.baseUrl}${n}${e}`,{method:`GET`,headers:this.headers,signal:t?.signal,...this.credentials?{credentials:this.credentials}:{}})}async request(e,n){let r=await this.send(e,n);if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}async requestOrNull(e,n){let r=await this.send(e,n);if(r.status===404)return null;if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}};function i(e){return new r(e)}function a(e){return encodeURIComponent(e)}function o(e){let t=new URLSearchParams;for(let[n,r]of Object.entries(e))r!=null&&r!==``&&t.append(n,String(r));let n=t.toString();return n?`?${n}`:``}async function s(e){try{return await e.text()}catch{return}}var c=`@viglet/shio-client`,l="// AUTO-GENERATED by @viglet/shio-client (shio-types). DO NOT EDIT BY HAND.\n// Re-run `shio-types` after changing a post-type.";function u(e,t={}){let n=t.importFrom??c,r=t.banner??l,i=[...e].sort((e,t)=>e.name.localeCompare(t.name)),a=new Map,o=new Set;for(let e of i){let t=h(e.name)||`PostType`,n=t,r=2;for(;o.has(n);)n=`${t}${r++}`;o.add(n),a.set(e.name,n)}let s=[];for(let e of i){let t=a.get(e.name),n=p(e.title??e.description,0);s.push(`${n}export interface ${t}Attrs {\n${d(e.fields,1)}}\n\n/** A \`${e.name}\` post with typed attributes. */\nexport type ${t}Post = ShioPost & {\n  postType: ${JSON.stringify(e.name)};\n  attrs: ${t}Attrs;\n};`)}let u=`/** Maps each post-type's API name to its typed post interface. */
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.ShioClient={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=class e extends Error{constructor(t,n,r){super(`Shio CDA ${t} for ${n}`),this.name=`ShioHttpError`,this.status=t,this.url=n,this.body=r,Object.setPrototypeOf(this,e.prototype)}},n=`/api/v2/cda`,r=class{constructor(e){if(!e?.baseUrl)throw Error("ShioClient: `baseUrl` is required");this.baseUrl=e.baseUrl.replace(/\/+$/,``),this.headers={Accept:`application/json`,...e.headers??{}},e.apiToken&&(this.headers.Key=e.apiToken);let t=e.fetch??globalThis.fetch;if(typeof t!=`function`)throw Error("ShioClient: no global `fetch` available — pass `fetch` in the config");this.fetchFn=t.bind(globalThis),this.credentials=e.credentials}getSites(e){return this.request(`/site`,e)}getSite(e,t){return this.requestOrNull(`/site/${a(e)}`,t)}getRedirects(e,t){return this.requestOrNull(`/site/${a(e)}/redirects`,t)}listChildren(e,t,n){let r=o({page:t?.page,size:t?.size,locale:t?.locale,state:t?.state});return this.requestOrNull(`/object/${a(e)}/list${r}`,n)}getPath(e,t){return this.requestOrNull(`/object/${a(e)}/path`,t)}getPost(e,t){let n=o({state:t?.state});return this.requestOrNull(`/post/${a(e)}${n}`,t)}getPostByUrl(e,t,n,r){let i=typeof n==`string`?n:void 0,a=typeof n==`string`?r:n,s=o({siteId:e,url:t,locale:i,state:a?.state});return this.requestOrNull(`/post/by-url${s}`,a)}getPostTypes(e){return this.request(`/post-type`,e)}getPostType(e,t){return this.requestOrNull(`/post-type/${a(e)}`,t)}query(e,t){let n=o({siteId:e?.siteId,folderId:e?.folderId,postType:e?.postType,page:e?.page,size:e?.size,locale:e?.locale,state:e?.state});return this.request(`/query${n}`,t)}async send(e,t){return this.fetchFn(`${this.baseUrl}${n}${e}`,{method:`GET`,headers:this.headers,signal:t?.signal,...this.credentials?{credentials:this.credentials}:{}})}async request(e,n){let r=await this.send(e,n);if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}async requestOrNull(e,n){let r=await this.send(e,n);if(r.status===404)return null;if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}};function i(e){return new r(e)}function a(e){return encodeURIComponent(e)}function o(e){let t=new URLSearchParams;for(let[n,r]of Object.entries(e))r!=null&&r!==``&&t.append(n,String(r));let n=t.toString();return n?`?${n}`:``}async function s(e){try{return await e.text()}catch{return}}var c=`@viglet/shio-client`,l="// AUTO-GENERATED by @viglet/shio-client (shio-types). DO NOT EDIT BY HAND.\n// Re-run `shio-types` after changing a post-type.";function u(e,t={}){let n=t.importFrom??c,r=t.banner??l,i=[...e].sort((e,t)=>e.name.localeCompare(t.name)),a=new Map,o=new Set;for(let e of i){let t=h(e.name)||`PostType`,n=t,r=2;for(;o.has(n);)n=`${t}${r++}`;o.add(n),a.set(e.name,n)}let s=[];for(let e of i){let t=a.get(e.name),n=p(e.title??e.description,0);s.push(`${n}export interface ${t}Attrs {\n${d(e.fields,1)}}\n\n/** A \`${e.name}\` post with typed attributes. */\nexport type ${t}Post = ShioPost & {\n  postType: ${JSON.stringify(e.name)};\n  attrs: ${t}Attrs;\n};`)}let u=`/** Maps each post-type's API name to its typed post interface. */
 export interface ShioPostTypes {\n${i.map(e=>`  ${m(e.name)}: ${a.get(e.name)}Post;`).join(`
 `)||``}\n}\n\n/** Union of all known post-type API names. */
 export type ShioPostTypeName = keyof ShioPostTypes;`;return`${r}\n\nimport type { ShioPost } from ${JSON.stringify(n)};\n\n`+(s.length?`${s.join(`
 
-`)}\n\n`:``)+`${u}\n`}function d(e,t){let n=`  `.repeat(t);return[...e].sort((e,t)=>e.ordinal-t.ordinal).map(e=>{let r=p(e.label??e.description,t),i=e.required?``:`?`;return`${r}${n}${m(e.name)}${i}: ${f(e,t)};\n`}).join(``)}function f(e,t){return e.fields&&e.fields.length>0?`Array<{\n${d(e.fields,t+1)}${`  `.repeat(t)}}>`:e.multiple?`string[]`:`string`}function p(e,t){return!e||!e.trim()?``:`${`  `.repeat(t)}/** ${e.trim().replace(/\*\//g,`*\\/`)} */\n`}function m(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e)?e:JSON.stringify(e)}function h(e){let t=(e??``).split(/[^A-Za-z0-9]+/).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(``);return/^[0-9]/.test(t)&&(t=`T${t}`),t}e.ShioClient=r,e.ShioHttpError=t,e.createShioClient=i,e.generateShioTypes=u});
+`)}\n\n`:``)+`${u}\n`}function d(e,t){let n=`  `.repeat(t);return[...e].sort((e,t)=>e.ordinal-t.ordinal).map(e=>{let r=p(e.label??e.description,t),i=e.required?``:`?`;return`${r}${n}${m(e.name)}${i}: ${f(e,t)};\n`}).join(``)}function f(e,t){return e.fields&&e.fields.length>0?`Array<{\n${d(e.fields,t+1)}${`  `.repeat(t)}}>`:e.multiple?`string[]`:`string`}function p(e,t){return!e||!e.trim()?``:`${`  `.repeat(t)}/** ${e.trim().replace(/\*\//g,`*\\/`)} */\n`}function m(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e)?e:JSON.stringify(e)}function h(e){let t=(e??``).split(/[^A-Za-z0-9]+/).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(``);return/^[0-9]/.test(t)&&(t=`T${t}`),t}var g=[`heading`,`paragraph`,`quote`,`list`,`code`,`image`,`embed`,`reference`];function _(e,t){let n=e.attrs?.[t];return Array.isArray(n)?n:null}e.SHIO_BLOCK_TYPES=g,e.ShioClient=r,e.ShioHttpError=t,e.createShioClient=i,e.generateShioTypes=u,e.shioBlocks=_});

package/dist/types.d.ts

@@ -39,6 +39,20 @@ export interface ShioRequestOptions {
     /** Abort signal for cancellation (e.g. React effect cleanup). */
     signal?: AbortSignal;
 }
+/**
+ * The version of content a CDA read asks for (SH1081, over SH990's parameter).
+ *
+ * `"published"` is the default and any token may read it. `"draft"` and `"rev:<n>"` need a
+ * preview token, and without one the read throws {@link ShioHttpError} with status 403 and the
+ * problem slug `state-needs-preview-token`. A string rather than a union, so the server stays the
+ * one place that says which values exist.
+ */
+export type ShioContentState = string;
+/** Per-request options for a single-post read: {@link ShioRequestOptions} plus a state. */
+export interface ShioReadOptions extends ShioRequestOptions {
+    /** See {@link ShioContentState}; omitted, the published version. */
+    state?: ShioContentState;
+}
 /** A published site. */
 export interface ShioSite {
     id: string;
@@ -46,6 +60,47 @@ export interface ShioSite {
     description?: string;
     url?: string;
     rootFolderId?: string;
+    /**
+     * The languages this site is in (SH1123) — what a language switcher is built from.
+     * Present on {@link ShioClient.getSite} and {@link ShioClient.getSites}; absent on the
+     * `site` a {@link ShioPath} carries.
+     */
+    locales?: ShioSiteLocales;
+}
+/**
+ * A site's locale policy (SH1123). Pair it with {@link ShioPost.availableLocales}: the
+ * site says which languages it offers, the post says which of them this page exists in.
+ */
+export interface ShioSiteLocales {
+    /** The locale the site is written in — always one of {@link enabled}. */
+    defaultLocale: string;
+    /** Every locale the site offers, in the order a switcher lists them. */
+    enabled: string[];
+    /**
+     * Locale to show instead when a page is missing in the one asked for, e.g.
+     * `{ "pt-br": "pt" }`. A locale with no entry falls back to {@link defaultLocale}.
+     */
+    fallback: Record<string, string>;
+    /**
+     * `true` when somebody chose this policy. `false` when it was read off the published
+     * content, in which case {@link enabled} lists what has been translated so far rather
+     * than what the site promises.
+     */
+    declared: boolean;
+}
+/**
+ * One row of a site's redirect table (SH1133), from {@link ShioClient.getRedirects}.
+ *
+ * A front end that serves the site's URLs itself consults this before answering 404: the
+ * instance's own renderer honours these, and a headless site never reaches it.
+ */
+export interface ShioRedirect {
+    /** The site-relative path that moved, e.g. `/pricing`. */
+    from: string;
+    /** Where it moved: a site-relative path, or an absolute URL as written. */
+    to: string;
+    /** `true` for a 301, `false` for a 302 — the default, because a wrong 301 is cached for ever. */
+    permanent: boolean;
 }
 /** A folder (listing item / breadcrumb node). */
 export interface ShioFolder {
@@ -88,7 +143,78 @@ export interface ShioPost {
     availableLocales: string[];
     /** Post-type attributes as a JSON object, keyed by attribute name. */
     attrs: Record<string, unknown>;
+    /**
+     * SH1016 — field name to rendered HTML, for this post's `Blocks` fields.
+     *
+     * Beside {@link attrs}, never instead of it: a site that maps block types to its own
+     * components reads the array out of `attrs`, and one that has been dropping a body into a
+     * div reads this. Absent for a post with no block field, which is every post written
+     * before the widget existed.
+     */
+    rendered?: Record<string, string>;
+}
+/**
+ * SH1016 — one block of a `Blocks` field, discriminated by {@link ShioBlock.type}.
+ *
+ * TypeScript narrows on `type`, so `switch (block.type)` gives each case its own fields with
+ * no cast — which is the whole reason the body is an array of these rather than a string.
+ * A `key` is the block's identity across a reorder, not its position.
+ *
+ * Marks are ranges over the block's own `text`, not nested spans: `<b><i>x</i></b>` and
+ * `<i><b>x</b></i>` are one content with two spellings, and a range has one.
+ */
+export interface ShioBlockMark {
+    from: number;
+    to: number;
+    type: "strong" | "em" | "code" | "link" | "strike";
+    /** Present on a `link` mark. */
+    href?: string;
 }
+interface ShioBlockBase {
+    key: string;
+}
+export type ShioBlock = (ShioBlockBase & {
+    type: "heading";
+    level: number;
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "paragraph";
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "quote";
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "list";
+    ordered?: boolean;
+    items?: string[];
+}) | (ShioBlockBase & {
+    type: "code";
+    language?: string;
+    text?: string;
+}) | (ShioBlockBase & {
+    type: "image";
+    src?: string;
+    alt?: string;
+}) | (ShioBlockBase & {
+    type: "embed";
+    url?: string;
+}) | (ShioBlockBase & {
+    type: "reference";
+    address?: string;
+});
+/** The registered block types, as the server refuses anything outside them. */
+export declare const SHIO_BLOCK_TYPES: readonly ["heading", "paragraph", "quote", "list", "code", "image", "embed", "reference"];
+/**
+ * Reads a post's block field as blocks, or `null` when it is not one.
+ *
+ * A helper rather than a cast, because the honest answer for a field that holds a string is
+ * "this is not a blocks field" — and a consumer that casts finds that out by rendering
+ * nothing.
+ */
+export declare function shioBlocks(post: ShioPost, field: string): ShioBlock[] | null;
 /** Folder children: subfolders plus a paged slice of published posts. */
 export interface ShioListing {
     folderId?: string;
@@ -148,9 +274,18 @@ export interface ShioQueryParams {
     postType?: string;
     page?: number;
     size?: number;
+    /** Only posts written in this locale (SH1057), e.g. `"pt-br"`; omitted, every locale. */
+    locale?: string;
+    /** SH1081 — which version of each post; see {@link ShioContentState}. */
+    state?: ShioContentState;
 }
 /** Paging parameters for listings. */
 export interface ShioPageParams {
     page?: number;
     size?: number;
+    /** Only posts written in this locale (SH1057); a folder's subfolders are listed whatever it is. */
+    locale?: string;
+    /** SH1081 — which version of each post; see {@link ShioContentState}. */
+    state?: ShioContentState;
 }
+export {};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@viglet/shio-client",
-  "version": "2026.3.2",
-  "description": "Framework-agnostic TypeScript client for the Shio CMS Content Delivery API (CDA). Zero runtime dependencies — works in Node, the browser, edge runtimes, Next.js server components, Astro, Vue, Svelte and plain scripts.",
-  "homepage": "https://shio.viglet.org/",
+  "version": "2026.3.3",
+  "description": "Framework-agnostic TypeScript client for the Viglet Shio Content Delivery API (CDA). Zero runtime dependencies — works in Node, the browser, edge runtimes, Next.js server components, Astro, Vue, Svelte and plain scripts.",
+  "homepage": "https://openviglet.github.io/shio/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openviglet/shio.git",
@@ -33,7 +33,7 @@
   "sideEffects": false,
   "devDependencies": {
     "typescript": "^5.8.3",
-    "vite": "^8.2.0"
+    "vite": "^8.3.5"
   },
   "keywords": [
     "shio",
@@ -65,6 +65,6 @@
     "dev": "vite build --watch",
     "build": "vite build && tsc --emitDeclarationOnly",
     "typecheck": "tsc --noEmit",
-    "test": "node --test \"test/*.test.mjs\""
+    "test": "node --import ../scripts/test-watchdog.mjs --test \"test/*.test.mjs\""
   }
 }