@craftware/crafty-sdk 0.6.0 → 0.8.0

package/skills/crafty-cms/references/sdk-development.md

@@ -23,7 +23,7 @@ const crafty = createCraftyClient({
 });
 ```
 
-`createCraftyClient(config)` returns a plain object with six resources (`collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`) and the visual editor helpers `attrs`, `attrsHtml` and `previewFromRequest`.
+`createCraftyClient(config)` returns a plain object with six resources (`collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`), the image helpers `image` and `srcset`, and the visual editor helpers `attrs`, `attrsHtml` and `previewFromRequest`.
 
 ### Config options
 
@@ -70,7 +70,7 @@ crafty.entries.list(collectionSlug, query?, options?)  // => { data: CraftyEntry
 crafty.entries.get(collectionSlug, id, options?)       // => { data: CraftyEntry }
 ```
 
-`query`: `sort_by`, `sort_order` (`asc`/`desc`), `per_page`, `page`, plus any extra key/value filters passed through to the API.
+`query`: `q` (text search over the collection's text fields), `sort_by`, `sort_order` (`asc`/`desc`), `per_page`, `page`, plus any extra key/value filters passed through to the API.
 
 ### `pages`
 
@@ -113,7 +113,7 @@ const cta = landing.requireBlock("cta");            // throws plain Error if abs
 | `boolean` | boolean |
 | `stringList` | `string[]` (e.g. `["AI", "Cloud"]`) |
 | `repeater` | array of objects; every declared subfield is present, `null` when empty (e.g. `[{ icon, title, text, tags: string[] }]`) |
-| `reference` | collection reference: entry summary `{ id, slug, label }` or `null`; media reference (`model: "Media"`): the media id, plus `<key>_media` with `{ id, url, file_name, mime_type, size, is_public }` or `null` |
+| `reference` | collection reference: entry summary `{ id, slug, label }` or `null`; media reference (`model: "Media"`): the media id, plus `<key>_media` with `{ id, url, file_name, mime_type, size, is_public, image_transform_base }` or `null` |
 | `multiReference` | collection: array of entries; media (`model: "Media"`): array of media ids, plus `<key>_media` with the files in the same order (missing files are skipped) |
 
 Entries expose media references the same way (`entry.image` is the id, `entry.image_media.url` the file).
@@ -124,21 +124,72 @@ const items = solutions?.data.items ?? [];
 items.map((item) => `${item.title}: ${item.tags.join(", ")}`);
 
 const hero = home.block("hero");
-const heroUrl = hero?.data.image_media?.url;           // reference, model "Media"
+const heroUrl = crafty.image(hero?.data.image_media, { width: 1600, format: "auto" }); // reference, model "Media"
 const slides = hero?.data.gallery_media ?? [];         // multiReference, model "Media"
 ```
 
+### Images: always go through `crafty.image()`
+
+Render every Crafty image with `crafty.image(media, { width, format: "auto" })` (and `crafty.srcset(media, widths, { format: "auto" })` for responsive images) instead of the raw `url`. Sites that ship the original upload fail Core Web Vitals (LCP).
+
+```tsx
+const photo = block.data.image_media;
+
+<img
+  src={crafty.image(photo, { width: 800, format: "auto" })}
+  srcSet={crafty.srcset(photo, [400, 800, 1200, 1600], { format: "auto" })}
+  sizes="(min-width: 768px) 50vw, 100vw"
+  width={800}
+  height={450}
+  loading="lazy"
+  alt={block.data.title ?? ""}
+/>
+```
+
+- `crafty.image(media, { width?, height?, fit?, quality?, format? })` → string. `media` is a `<key>_media` object, a `CraftyMediaFile`, or a URL string. `width`/`height` 1–4096, `quality` 1–100, `fit`: `scale-down` | `contain` | `cover` | `crop` | `pad`, `format`: `auto` | `webp` | `avif` | `jpeg` | `png`. Invalid options are dropped.
+- `crafty.srcset(media, widths, options?)` → `"<url> 400w, <url> 800w"`, or `""` when the image cannot be transformed.
+- Pick `width` from the rendered size (about 2x for retina on small images); use `fit: "cover"` with both `width` and `height` for fixed-ratio cards and thumbnails.
+- Transforms only apply to **public** raster images when the Crafty server has Cloudflare Image Transformations enabled (the media then carries `image_transform_base`). Otherwise `image()` returns the original `url` and `srcset()` returns `""`, so the same code always works. Upload images to a public repository (`manage_media_collection` with `is_public: true`) when the site needs permanent, resizable URLs.
+- Use `og:image` with `crafty.image(media, { width: 1200, height: 630, fit: "cover", format: "jpeg" })`: social scrapers do not support AVIF/WebP negotiation.
+- Do not hand-build `/cdn-cgi/image/...` URLs or append `?w=` query parameters.
+
 Prefer modelling lists as `repeater` / `stringList` fields on a block type over collections or `json` fields; see the `crafty-cms` skill.
 
+### Generated types (`crafty types`)
+
+Do not guess field keys or shapes: generate them from the site's real content models with the CLI.
+
+```bash
+npx @craftware/crafty-cli types                       # CRAFTY_API_URL + CRAFTY_API_KEY from .env
+npx @craftware/crafty-cli types --api-key=$KEY --url=https://<tenant>.crafty.do --out=src/crafty.types.ts
+```
+
+It reads `GET /api/v1/schema` (JSON Schema of every collection and block type of the API key's environment, versioned by `format_version`) and writes `crafty.types.ts`:
+
+- `<Slug>Entry` per collection (entry metadata + fields), `<Slug>BlockData` and `<Slug>Block` per block type, the `CraftyPageBlock` union (discriminated by `type`), the `CraftyCollectionTypes` / `CraftyBlockDataTypes` slug maps, and `CraftyEntryReference` / `CraftyMediaSummary`.
+- `select` → union of option values, `stringList` → `string[]`, `repeater` → array of item objects, `json` → `unknown`; optional fields are `| null`.
+
+```ts
+import type { CarsEntry, CraftyPageBlock } from "./crafty.types";
+
+const cars = (await crafty.entries.list("cars")).data as unknown as CarsEntry[];
+const page = await crafty.pages.get("home");
+for (const block of page.blocks as unknown as CraftyPageBlock[]) {
+  if (block.type === "hero") block.data.heading; // HeroBlockData
+}
+```
+
+Types depend on the environment (generate with the key of the environment the code targets) and go stale when a collection or block type changes — re-run the command after `create_block_type`, `update_block_type`, `create_collection` or `update_collection`.
+
 ### `forms`
 
 ```ts
 crafty.forms.list(options?)                  // => { data: CraftyForm[] }            (requires apiKey)
 crafty.forms.get(slug, options?)             // => { data: CraftyForm }              (requires apiKey)
-crafty.forms.submit(formSlug, data, options?) // => { id, form_id, submitted_at }   (public, no apiKey)
+crafty.forms.submit(formSlug, data, options?) // => { id, form_id, submitted_at }   (public; apiKey optional, picks the environment)
 ```
 
-`forms.submit()` uses a **public** endpoint: it sends no `X-API-Key`, but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
+`forms.submit()` uses a **public** endpoint: the `X-API-Key`, when configured, only selects the environment (a staging key submits to staging, no key submits to production), but it **requires `siteSlug` in the client config** — calling it without one throws a synchronous `CraftyError` with code `BAD_REQUEST`.
 
 ```ts
 const crafty = createCraftyClient({
@@ -170,7 +221,7 @@ crafty.mediaCollections.list(query?, options?)  // => { data: CraftyMediaCollect
 crafty.mediaFiles.list(query?, options?)  // => { data: CraftyMediaFile[], links, meta: { ...pagination, ttl_minutes } }
 ```
 
-`query`: `collection`, `directory_id`, `ttl_minutes` (signed-URL lifetime), `per_page`, `page`.
+`query`: `collection`, `directory_id`, `ttl_minutes` (signed-URL lifetime), `per_page`, `page`. Each file has `url`, `is_public`, `expires_at` and `image_transform_base`; pass the file to `crafty.image()` to render it.
 
 ## `llms.txt`
 
@@ -284,6 +335,7 @@ try {
 
 - `attrs(target, field, { label? })` / `crafty.attrs(...)` → `{ "data-crafty-block" | "data-crafty-entry", "data-crafty-field", "data-crafty-label"? }` to spread on the element that renders the value; `{}` when the target has no valid id. `field` is a field key or a path into a list or JSON value (`sections[3].title`, `items[2].title` for a block-type `repeater`, `tags[1]` for a `stringList`, `items[0].tags[1]` for a stringList inside a repeater item). The index is the item's position in the stored data.
 - `attrsHtml(target, field, { label? })` → the same attributes as an escaped HTML string.
+- `image(media, options?)` / `crafty.image(...)` and `srcset(media, widths, options?)` / `crafty.srcset(...)` → resized image URLs; see "Images: always go through `crafty.image()`".
 - `previewFromRequest(req)` → preview token of an incoming request (URL string, `URL`, Web `Request`, Node `req.url`, Express `req.query`) or `null`.
 - `readPreviewToken()` → token in the browser, or `null`.
 - `enableVisualEditing(options)` from `@craftware/crafty-sdk/visual-editing` → connects the page to the editor; no-op outside the admin iframe. Options: `onRefresh`, `adminOrigins`, `page`, `entries`, `touchHighlightMs`.