@webiny/mcp 6.1.0 → 6.2.0

package/skills/webiny-sdk/SKILL.md

@@ -6,8 +6,9 @@ description: >
   Use this skill when the developer is building a Next.js, Vue, Node.js, or any external app
   that needs to fetch or write content to Webiny, set up the SDK, use the Result pattern,
   list/get/create/update/publish entries, filter and sort queries, use TypeScript generics
-  for type safety, work with the File Manager, or create API keys programmatically. Also
-  covers the three API types (Read, Manage, Preview) and CmsEntryData typing.
+  for type safety, work with the File Manager, list languages, or create API keys programmatically.
+  Covers read vs preview mode, the `values` wrapper requirement, correct method names,
+  and the `fields` required parameter.
 ---
 
 # Webiny SDK
@@ -26,9 +27,9 @@ Initialize once and reuse:
 
 ```typescript
 // lib/webiny.ts
-import { Sdk } from "@webiny/sdk";
+import { Webiny } from "@webiny/sdk";
 
-export const sdk = new Sdk({
+export const webiny = new Webiny({
   token: process.env.WEBINY_API_TOKEN!,
   endpoint: process.env.WEBINY_API_ENDPOINT!,
   tenant: process.env.WEBINY_API_TENANT || "root"
@@ -36,30 +37,50 @@ export const sdk = new Sdk({
 ```
 
 - `token` -- API key token generated in Webiny Admin (Settings > API Keys)
-- `endpoint` -- The base CloudFront URL (e.g., `https://xxx.cloudfront.net`). Run `yarn webiny info` to find it.
+- `endpoint` -- The base API URL, **without a trailing slash**. Run `yarn webiny info` in your Webiny project to find the API URL. For Website Builder projects use `NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST`.
 - `tenant` -- Tenant ID, defaults to `"root"`
 
-## The Three API Types
+> **IMPORTANT:** Never add a trailing slash to `endpoint`. The SDK appends `/graphql` to the endpoint internally, so `https://xxx.cloudfront.net/` will break all requests.
 
-Webiny provides three separate GraphQL APIs:
+## The `fields` Parameter (Required)
 
-| API         | URL Path       | Returns                               | Can Write | Use For                       |
-| ----------- | -------------- | ------------------------------------- | --------- | ----------------------------- |
-| **Read**    | `/cms/read`    | Published entries only                | No        | Public-facing apps, SSG       |
-| **Manage**  | `/cms/manage`  | All revisions (drafts + published)    | Yes       | Admin tools, content creation |
-| **Preview** | `/cms/preview` | Latest revisions (drafts + published) | No        | Content preview               |
+Every SDK method requires a `fields` array that specifies which fields to return. Omitting it will cause a runtime error.
 
-The SDK automatically routes to the correct API based on the method:
+- Use `"values.<fieldId>"` for content fields: `"values.name"`, `"values.price"`
+- Use top-level field names for metadata: `"id"`, `"entryId"`, `"createdOn"`, `"status"`
+- Use dot notation for nested fields: `"values.author.name"`
 
-- `listEntries`, `getEntry` -> Read API
-- `createEntry`, `updateEntry`, `publishEntry`, `unpublishEntry` -> Manage API
+```typescript
+// Minimal fields -- just IDs
+fields: ["id", "entryId"];
+
+// Content fields
+fields: ["id", "entryId", "values.name", "values.price", "values.description"];
+
+// Nested reference fields
+fields: ["id", "values.title", "values.author.name", "values.author.email"];
+```
+
+## CMS: Read vs Preview Mode
+
+`webiny.cms.listEntries` and `webiny.cms.getEntry` accept a `preview` parameter to control which revisions are returned:
+
+| `preview`         | Returns                              | Use For                          |
+| ----------------- | ------------------------------------ | -------------------------------- |
+| `false` (default) | Published entries only               | Public-facing apps, SSG          |
+| `true`            | Latest revision (draft or published) | Content preview, editorial tools |
+
+Write operations (`createEntry`, `updateEntryRevision`, etc.) are not affected by `preview`.
 
 ## The Result Pattern
 
 Every SDK method returns a `Result` object -- it never throws:
 
 ```typescript
-const result = await sdk.cms.listEntries({ modelId: "product", fields: ["id"] });
+const result = await webiny.cms.listEntries({
+  modelId: "product",
+  fields: ["id", "values.name"]
+});
 
 if (result.isOk()) {
   console.log(result.value.data); // success -- typed data
@@ -88,8 +109,9 @@ interface ProductCategory {
   slug: string;
 }
 
-const result = await sdk.cms.listEntries<Product>({
-  modelId: "product"
+const result = await webiny.cms.listEntries<Product>({
+  modelId: "product",
+  fields: ["id", "entryId", "values.name", "values.price", "values.sku"]
 });
 
 if (result.isOk()) {
@@ -106,9 +128,10 @@ Reference fields like `category` are typed as `CmsEntryData<T>`, which wraps ref
 ### List Entries
 
 ```typescript
-const result = await sdk.cms.listEntries<Product>({
+const result = await webiny.cms.listEntries<Product>({
   modelId: "product",
-  sort: ["values.name_ASC"],
+  fields: ["id", "entryId", "values.name", "values.price"],
+  sort: { "values.name": "asc" },
   limit: 10
 });
 ```
@@ -116,13 +139,14 @@ const result = await sdk.cms.listEntries<Product>({
 ### List with Filters
 
 ```typescript
-const result = await sdk.cms.listEntries<Product>({
+const result = await webiny.cms.listEntries<Product>({
   modelId: "product",
+  fields: ["id", "entryId", "values.name", "values.price"],
   where: {
     "values.price_gte": 100,
     "values.name_contains": "Pro"
   },
-  sort: ["values.price_DESC"]
+  sort: { "values.price": "desc" }
 });
 ```
 
@@ -140,78 +164,151 @@ const result = await sdk.cms.listEntries<Product>({
 
 ### Sort Format
 
-Sort strings follow the pattern `values.<fieldId>_ASC` or `values.<fieldId>_DESC`:
+Sort is a `Record<string, "asc" | "desc">` object:
 
 ```typescript
-sort: ["values.name_ASC"]; // alphabetical
-sort: ["values.price_DESC"]; // highest price first
-sort: ["values.createdOn_DESC"]; // newest first
+sort: { "values.name": "asc" }     // alphabetical
+sort: { "values.price": "desc" }   // highest price first
+sort: { "values.createdOn": "desc" } // newest first
 ```
 
 ### Get Single Entry
 
+Use `where` with either `id` (revision ID) or `entryId`:
+
 ```typescript
-const result = await sdk.cms.getEntry<Product>({
+// By revision ID
+const result = await webiny.cms.getEntry<Product>({
   modelId: "product",
-  id: "abc123#0001"
+  where: { id: "abc123#0001" },
+  fields: ["id", "entryId", "values.name", "values.price"]
+});
+
+// By entry ID (gets latest published revision)
+const result = await webiny.cms.getEntry<Product>({
+  modelId: "product",
+  where: { entryId: "abc123" },
+  fields: ["id", "entryId", "values.name"]
 });
 ```
 
-### The `fields` Parameter
+### Preview Mode (Drafts)
 
-Control which fields are returned:
+Pass `preview: true` to `listEntries` or `getEntry` to access unpublished/draft content:
 
 ```typescript
-const result = await sdk.cms.listEntries<Product>({
+const result = await webiny.cms.listEntries<Product>({
   modelId: "product",
-  fields: ["id", "values.name", "values.price"]
+  fields: ["id", "entryId", "values.name"],
+  preview: true // returns drafts + published
 });
 ```
 
-When omitted, all fields are returned. The `depth` parameter (default: `1`) controls how deeply reference fields are resolved.
-
 ## Writing Data
 
+> **CRITICAL:** Content fields MUST be wrapped inside a `values` key in the `data` object. Passing fields directly (without `values`) will result in an empty or malformed entry.
+
 ### Create an Entry
 
 ```typescript
-const result = await sdk.cms.createEntry({
+const result = await webiny.cms.createEntry({
   modelId: "contactSubmission",
   data: {
-    name: "John Doe",
-    email: "john@example.com",
-    message: "Hello from the contact form!"
-  }
+    values: {
+      // ← REQUIRED: wrap all content fields in `values`
+      name: "John Doe",
+      email: "john@example.com",
+      message: "Hello from the contact form!"
+    }
+  },
+  fields: ["id", "entryId"]
 });
 ```
 
-### Update an Entry
+### Update an Entry Revision
+
+The method is `updateEntryRevision`, not `updateEntry`. Use `revisionId` (the full `entryId#revisionNumber`, e.g. `"abc123#0001"`):
 
 ```typescript
-const result = await sdk.cms.updateEntry({
+const result = await webiny.cms.updateEntryRevision({
   modelId: "product",
-  id: "abc123#0001",
+  revisionId: "abc123#0001", // ← note: revisionId, not id
   data: {
-    price: 29.99
-  }
+    values: {
+      // ← REQUIRED: wrap fields in `values`
+      price: 29.99
+    }
+  },
+  fields: ["id", "entryId", "values.price"]
 });
 ```
 
 ### Publish / Unpublish
 
+The methods are `publishEntryRevision` and `unpublishEntryRevision`, not `publishEntry`/`unpublishEntry`. Both require `revisionId` and `fields`:
+
 ```typescript
-await sdk.cms.publishEntry({ modelId: "product", id: "abc123#0001" });
-await sdk.cms.unpublishEntry({ modelId: "product", id: "abc123#0001" });
+await webiny.cms.publishEntryRevision({
+  modelId: "product",
+  revisionId: "abc123#0001",
+  fields: ["id", "entryId", "status"]
+});
+
+await webiny.cms.unpublishEntryRevision({
+  modelId: "product",
+  revisionId: "abc123#0001",
+  fields: ["id", "entryId", "status"]
+});
+```
+
+### Delete an Entry Revision
+
+```typescript
+await webiny.cms.deleteEntryRevision({
+  modelId: "product",
+  revisionId: "abc123#0001",
+  fields: []
+});
+```
+
+## Languages
+
+`webiny.languages.listLanguages()` returns all **enabled** languages — disabled languages are always filtered out server-side, so no filter parameter is needed.
+
+```typescript
+import type { Language } from "@webiny/sdk";
+
+const result = await webiny.languages.listLanguages();
+
+if (result.isOk()) {
+  const languages: Language[] = result.value;
+  // languages[0].code, .name, .direction, .isDefault
+}
+```
+
+The `Language` type:
+
+```typescript
+interface Language {
+  id: string;
+  code: string;        // e.g. "en-US"
+  name: string;        // e.g. "English (US)"
+  direction?: "ltr" | "rtl";
+  isDefault?: boolean;
+}
 ```
 
 ## File Manager
 
 ```typescript
 // List files
-const files = await sdk.fileManager.listFiles({ limit: 20 });
+const files = await webiny.fileManager.listFiles({
+  limit: 20,
+  fields: ["id", "key", "name", "size", "type", "src"]
+});
 
-// Upload a file
-const uploaded = await sdk.fileManager.uploadFile({ file: myFile });
+// Upload a file (returns presigned URL for direct S3 upload)
+const uploaded = await webiny.fileManager.uploadFile({ file: myFile });
 ```
 
 ## Creating API Keys via Code
@@ -249,21 +346,38 @@ Register (**YOU MUST include the `.ts` file extension in the `src` prop** — om
 
 ## SDK Modules Reference
 
-| Module               | Webiny App      | What You Can Do                                       |
-| -------------------- | --------------- | ----------------------------------------------------- |
-| `sdk.cms`            | Headless CMS    | List, get, create, update, publish, unpublish entries |
-| `sdk.fileManager`    | File Manager    | List, upload, and manage files and folders            |
-| `sdk.websiteBuilder` | Website Builder | List and retrieve website builder content             |
+| Module                 | Webiny App    | What You Can Do                                                       |
+| ---------------------- | ------------- | --------------------------------------------------------------------- |
+| `webiny.cms`           | Headless CMS  | List, get, create, update, publish, unpublish, delete entry revisions |
+| `webiny.fileManager`   | File Manager  | List, upload, and manage files and folders                            |
+| `webiny.tenantManager` | Multi-tenancy | Create, install, enable, disable tenants                              |
+| `webiny.languages`     | Languages     | List enabled languages (id, code, name, direction, isDefault)         |
+
+## Common Mistakes
+
+| Mistake                     | Correct                                 |
+| --------------------------- | --------------------------------------- |
+| `data: { name: "..." }`     | `data: { values: { name: "..." } }`     |
+| `updateEntry(...)`          | `updateEntryRevision(...)`              |
+| `publishEntry(...)`         | `publishEntryRevision(...)`             |
+| `unpublishEntry(...)`       | `unpublishEntryRevision(...)`           |
+| `sort: ["values.name_ASC"]` | `sort: { "values.name": "asc" }`        |
+| `getEntry({ id: "..." })`   | `getEntry({ where: { id: "..." } })`    |
+| Omitting `fields`           | Always provide `fields: [...]`          |
+| Trailing slash in endpoint  | Remove trailing slash from endpoint URL |
 
 ## Quick Reference
 
 ```
-Install:        npm install @webiny/sdk
-Import:         import { Sdk } from "@webiny/sdk";
-Type import:    import type { CmsEntryData } from "@webiny/sdk";
-Initialize:     new Sdk({ token, endpoint, tenant })
-Result check:   result.isOk() -> result.value.data / result.error.message
-API endpoint:   yarn webiny info (in your Webiny project)
+Install:          npm install @webiny/sdk
+Import:           import { Webiny } from "@webiny/sdk";
+Type import:      import type { CmsEntryData } from "@webiny/sdk";
+Initialize:       new Webiny({ token, endpoint, tenant })
+Result check:     result.isOk() -> result.value.data / result.error.message
+API endpoint:     yarn webiny info (in your Webiny project) -- NO trailing slash
+Preview mode:     pass preview: true to listEntries / getEntry
+fields required:  every method needs a fields: string[] array
+values wrapper:   createEntry/updateEntryRevision data must use { values: { ... } }
 ```
 
 ## Related Skills