@wix/agent-skills 1.0.0

package/skills/wix-app/references/BACKEND_API.md

@@ -0,0 +1,233 @@
+
+# Wix Backend API Builder
+
+Creates HTTP endpoints for Wix CLI applications — server-side routes that handle HTTP requests, process data, and return responses. HTTP endpoints are powered by Astro endpoints and are automatically discovered from the file system.
+
+**Key facts:**
+
+- Files live in `src/pages/api/` with `.ts` extension
+- Cannot be added via `npm run generate` — create files directly
+- Don't appear on the Extensions page in the app dashboard
+- No extension registration needed (auto-discovered)
+- Replace the legacy "HTTP functions" from the previous Wix CLI for Apps
+
+## Use Cases
+
+Use HTTP endpoints when you need to:
+
+- Build REST APIs with multiple HTTP methods
+- Integrate with external APIs or services
+- Handle complex form submissions or file uploads
+- Serve dynamic content (images, RSS feeds, personalized data)
+- Access runtime data or server-side databases
+
+## File Structure and Naming
+
+### Basic Endpoint
+
+File path determines the endpoint URL:
+
+```
+src/pages/api/<your-endpoint-name>.ts
+```
+
+### Dynamic Routes
+
+Use square brackets for dynamic parameters:
+
+```
+src/pages/api/users/[id].ts → /api/users/:id
+src/pages/api/posts/[slug].ts → /api/posts/:slug
+src/pages/api/users/[userId]/posts/[postId].ts → /api/users/:userId/posts/:postId
+```
+
+## HTTP Methods
+
+Export named functions for each HTTP method. Type with `APIRoute` from `astro`. Each handler receives a `request` object and returns a `Response`:
+
+```typescript
+import type { APIRoute } from "astro";
+
+export const GET: APIRoute = async ({ request }) => {
+  console.log("Log from GET."); // This message logs to your CLI.
+  return new Response("Response from GET."); // This response is visible in the browser console
+};
+
+export const POST: APIRoute = async ({ request }) => {
+  const data = await request.json();
+  console.log("Log POST with body: ", data); // This message logs to your CLI.
+  return new Response(JSON.stringify(data)); // This response is visible in the browser console.
+};
+```
+
+## Request Handling
+
+### Path Parameters
+
+```typescript
+export const GET: APIRoute = async ({ params }) => {
+  const { id } = params; // From /api/users/[id]
+
+  if (!id) {
+    return new Response(JSON.stringify({ error: "ID required" }), {
+      status: 400,
+      statusText: "Bad Request",
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // Use id to fetch data
+};
+```
+
+### Query Parameters
+
+Use `new URL(request.url).searchParams`:
+
+```typescript
+export const GET: APIRoute = async ({ request }) => {
+  const url = new URL(request.url);
+  const search = url.searchParams.get("search");
+  const limit = parseInt(url.searchParams.get("limit") || "10", 10);
+  const offset = parseInt(url.searchParams.get("offset") || "0", 10);
+
+  // Use query parameters
+};
+```
+
+### Request Body
+
+Parse JSON body from POST/PUT/PATCH requests:
+
+```typescript
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const { title, content } = body;
+
+    if (!title || !content) {
+      return new Response(
+        JSON.stringify({ error: "Title and content required" }),
+        {
+          status: 400,
+          statusText: "Bad Request",
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Process data
+  } catch {
+    return new Response(JSON.stringify({ error: "Invalid JSON" }), {
+      status: 400,
+      statusText: "Bad Request",
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+};
+```
+
+### Headers
+
+```typescript
+const authHeader = request.headers.get("Authorization");
+const contentType = request.headers.get("Content-Type");
+```
+
+## Response Patterns
+
+Always return a `Response` object with proper status codes and headers:
+
+```typescript
+// 200 OK
+return new Response(JSON.stringify({ data: result }), {
+  status: 200,
+  headers: { "Content-Type": "application/json" },
+});
+
+// 201 Created
+return new Response(JSON.stringify({ id: newId, ...data }), {
+  status: 201,
+  headers: { "Content-Type": "application/json" },
+});
+
+// 204 No Content (for DELETE)
+return new Response(null, { status: 204 });
+
+// 400 Bad Request
+return new Response(JSON.stringify({ error: "Invalid input" }), {
+  status: 400,
+  statusText: "Bad Request",
+  headers: { "Content-Type": "application/json" },
+});
+
+// 404 Not Found
+return new Response(JSON.stringify({ error: "Not found" }), {
+  status: 404,
+  statusText: "Not Found",
+  headers: { "Content-Type": "application/json" },
+});
+
+// 500 Internal Server Error
+return new Response(JSON.stringify({ error: "Internal server error" }), {
+  status: 500,
+  statusText: "Internal Server Error",
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+## Frontend Integration
+
+Call HTTP endpoints from frontend components using Wix's built-in HTTP client (`httpClient.fetchWithAuth()`):
+
+```typescript
+import { httpClient } from "@wix/essentials";
+
+// GET request
+const baseApiUrl = new URL(import.meta.url).origin;
+const res = await httpClient.fetchWithAuth(
+  `${baseApiUrl}/api/<your-endpoint-name>`,
+);
+const data = await res.text();
+
+// POST request
+const res = await httpClient.fetchWithAuth(
+  `${baseApiUrl}/api/<your-endpoint-name>`,
+  {
+    method: "POST",
+    body: JSON.stringify({ message: "Hello from frontend" }),
+  },
+);
+const data = await res.json();
+```
+
+## Build, Deploy, and Delete
+
+To take HTTP endpoints to production, build and release your project:
+
+1. Build the project assets using the [`build`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build) command.
+2. Optionally create preview URLs using the [`preview`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/preview) command to share with team members for testing.
+3. Release your project using the [`release`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release) command.
+
+Once released, endpoints are accessible at production URLs and handle live traffic.
+
+To delete an HTTP endpoint, remove the file under `src/pages/api/` and release again.
+
+## Output Structure
+
+```
+src/pages/api/
+├── users.ts              # /api/users endpoint
+├── users/
+│   └── [id].ts           # /api/users/:id endpoint
+└── posts.ts              # /api/posts endpoint
+```
+
+## Backend-API-specific Conventions
+
+- Type all handlers with `APIRoute` from `astro`.
+- Always return `Response` objects with `JSON.stringify()` for JSON.
+- Use proper HTTP status codes (200, 201, 204, 400, 404, 500).
+- Include `Content-Type: application/json` header on JSON responses.
+- Include `statusText` in error responses.
+- Validate input parameters and request bodies.

package/skills/wix-app/references/BACKEND_EVENT.md

@@ -0,0 +1,116 @@
+
+# Wix CLI Backend Event Extension
+
+Creates event extensions for Wix CLI applications. Events are triggered when specific conditions occur—on a Wix user's site for app projects, or on your project's site for headless projects. Your project responds using event extensions built on JavaScript SDK webhooks; the CLI subscribes your project to these webhooks.
+
+Common use cases: run logic when a contact is created, an order is placed, a booking is confirmed, or a blog post is published.
+
+## Quick Start Checklist
+
+Follow these steps in order when creating an event extension.
+
+1. [ ] Create event folder: `src/extensions/backend/events/<event-name>/`
+2. [ ] Create `<event-name>.ts` with the SDK event import and handler function
+3. [ ] Create `<event-name>.extension.ts` with `extensions.event()` and a unique UUID
+4. [ ] Update `src/extensions.ts` to import and use the new extension
+
+**User (manual):** Configure app permissions for the event in the app dashboard if required; release a version and trigger the event to test.
+
+## References
+
+| Topic | Reference |
+| --- | --- |
+| Common events (CRM, eCommerce, Bookings, Blog) | [COMMON-EVENTS.md](backend-event/COMMON-EVENTS.md) |
+
+## Output Structure
+
+Two files per event ([docs](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/events/event-extension-files-and-code)). Only **one** handler per event allowed in the app (including dashboard handlers).
+
+```
+src/extensions/backend/events/<event-name>/
+├── <event-name>.extension.ts   # Builder: extensions.event({ id, source }) – id is unique GUID
+└── <event-name>.ts             # Handler: imports SDK event (e.g. onContactCreated), runs on trigger
+```
+
+## Implementation Pattern
+
+### Event builder (`<event-name>.extension.ts`)
+
+Use `extensions.event()` from `@wix/astro/builders`. Required fields: `id` (unique GUID), `source` (path to the handler file).
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const eventContactCreated = extensions.event({
+  id: "{{GENERATE_UUID}}",
+  source: "./extensions/backend/events/contact-created/contact-created.ts",
+});
+```
+
+**CRITICAL: UUID Generation**
+
+The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension—do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
+
+### Event handler (`<event-name>.ts`)
+
+Import the event from the correct SDK module and pass a handler. Wix invokes the handler with the event payload and metadata when the event occurs. Handler signatures are documented in the [JavaScript SDK reference](https://dev.wix.com/docs/sdk).
+
+```typescript
+import { contacts } from "@wix/crm";
+
+export default contacts.onContactCreated((event) => {
+  console.log("Contact created:", event.entity);
+  // Custom logic: sync to CRM, send welcome email, etc.
+});
+```
+
+Handler can be `async`; ensure errors are caught and logged so one failing handler does not break others.
+
+## Extension Registration
+
+**Two steps required.**
+
+### Step 1: Event builder file
+
+Create `<event-name>.extension.ts` inside the event folder (and `<event-name>.ts` for the handler) as shown in [Implementation Pattern](#implementation-pattern) above.
+
+### Step 2: Register in main extensions.ts
+
+**CRITICAL:** Read [Extension Registration reference](EXTENSION_REGISTRATION.md) and add the event extension to `src/extensions.ts` (import and `.use(eventContactCreated)` or equivalent). Without this, the event extension is not active.
+
+Naming: export names follow `event{CamelCaseName}` (e.g. `eventContactCreated`, `eventOrderPaid`).
+
+## Elevating Permissions for API Calls
+
+When calling Wix APIs from inside an event handler, use `auth.elevate` from `@wix/essentials` so the call runs with the right permissions.
+
+```typescript
+import { contacts } from "@wix/crm";
+import { auth } from "@wix/essentials";
+import { items } from "@wix/data";
+
+export default contacts.onContactCreated(async (event) => {
+  const elevatedQuery = auth.elevate(items.query);
+  const result = await elevatedQuery("MyCollection").find();
+  // Use result
+});
+```
+
+## Key Constraints
+
+- **One handler per event** – You cannot have two event extensions for the same event in the app (local or dashboard).
+- **Permissions** – Each event may require specific permission scopes; configure them in the app dashboard (Permissions page).
+- **Testing** – Release a version with your changes, then perform the action that triggers the event. Some events are not fully testable in local dev.
+- **Backend limits** – Event handlers run under backend extension limits (e.g. 1000 CPU ms per request, 20 sub-requests). See [About Backend Extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/about-backend-extensions).
+
+## Best Practices
+
+- **Error handling:** Wrap handler logic in try/catch; log and optionally rethrow or report.
+- **Idempotency:** Events may be delivered more than once; design handlers to be idempotent where possible.
+- **Logging:** Use `console.log` for debugging; keep production logs minimal and non-sensitive.
+- **Performance:** Finish within backend limits; offload heavy work to queues or background jobs if needed.
+
+## Testing Event Extensions
+
+1. **Release** a version with your changes.
+2. **Trigger** the event by taking an action.

package/skills/wix-app/references/CODE_QUALITY.md

@@ -0,0 +1,33 @@
+# Code Quality Requirements
+
+Applies to all generated code across every Wix CLI app extension type. Each per-extension reference links here instead of restating these rules.
+
+## TypeScript Quality Guidelines
+
+- Generated code MUST compile with zero TypeScript errors under strict settings: `strict`, `noImplicitAny`, `strictNullChecks`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`.
+- Prefer type-narrowing and exhaustive logic over assertions; avoid non-null assertions (`!`) and unsafe casts (`as any`).
+- Treat optional values, refs, and array indexing results as possibly undefined and handle them explicitly.
+- Use exhaustive checks for unions (e.g., `switch` with a `never` check) and return total values (no implicit `undefined`).
+- Do NOT use `// @ts-ignore` or `// @ts-expect-error`; fix the types or add guards instead.
+
+## Core Principles
+
+- Do NOT invent or assume new types, modules, functions, props, events, or imports. Use only entities present in the provided references or standard libraries already used in this project.
+- NEVER use mocks, placeholders, or TODOs in shipped code. ALWAYS implement complete, production-ready functionality.
+- If a required API, type, or module is missing, surface it to the user explicitly rather than inserting placeholder code.
+- Do NOT create README.md, CHANGELOG.md, or other unprompted markdown documentation — only output the files the task actually requires.
+
+## Code Quality Standards
+
+- Add documentation only for complex or non-obvious logic — well-named identifiers should carry the rest.
+- Prefer `async`/`await` for asynchronous operations.
+
+## Modular Code
+
+- If a generated file would exceed ~300 lines, split it into multiple smaller files with imports. Each component or function should stay ~50–100 lines.
+- Extract utilities/helpers into separate files; put types/interfaces into dedicated type files.
+
+## Error Handling
+
+- Log errors with `console.error` for debugging.
+- Handle network timeouts and external service failures.