Execute TypeScript code in an isolated workerd sandbox with a fully typed Magento 2 REST API client. ## Sandbox environment Your code runs inside an async IIFE — the **last expression** is captured and returned as JSON. Only one global is available: - `api` — a fully typed Magento REST client (generated by swagger-typescript-api from the instance's live OpenAPI schema). Authentication (bearer token) and base URL are pre-configured; every method is ready to call without extra setup. ## CRITICAL — return ONLY what you need **NEVER return raw Magento API responses.** They are huge and will exceed the response size limit. Instead, process the data inside the sandbox and return only the minimal result needed for the task. BAD — returns the entire product list (megabytes): ```ts return await api.v1.someProductListMethod({ searchCriteria: { pageSize: 50 } }); ``` GOOD — extracts only what's needed: ```ts const res = await api.v1.someProductListMethod({ searchCriteria: { pageSize: 50 } }); return { total: res.data?.total_count, skus: res.data?.items?.map(p => ({ sku: p.sku, name: p.name, price: p.price })), }; ``` ## Combine multiple API calls in a single eval Each eval_in_workerd call has overhead (bundling, starting workerd). **Batch related API calls into one eval** and return one combined result. You can use full JavaScript — variables, loops, try/catch, Promise.all, etc. ```ts // Fetch order + its items + customer in one eval const order = await api.v1.someOrderGetMethod(42); const customer = await api.v1.someCustomerGetMethod(order.data?.customerId); return { orderId: order.data?.entityId, status: order.data?.status, customerEmail: customer.data?.email, itemCount: order.data?.items?.length, }; ``` ## IMPORTANT — discover method names before calling them Method names are auto-generated and vary per Magento instance. **NEVER guess method names.** Always discover them first: Step 1 — Find available namespaces: ```ts return Object.keys(api).filter(k => typeof api[k] === 'object'); ``` Step 2 — List methods in a namespace (e.g. `v1`): ```ts return Object.keys(api.v1); ``` Step 3 — Find the right method by keyword search: ```ts // Search for product-related methods return Object.keys(api.v1).filter(k => k.toLowerCase().includes('product')); ``` Step 4 — Once you know the exact method name, call it and extract only the fields you need: ```ts const res = await api.v1.theExactMethodNameYouFound({ ... }); return { count: res.data?.total_count, items: res.data?.items?.map(i => i.sku) }; ``` ## API client structure `api` is an instance of the generated `Api` class. All endpoint methods live under **route namespaces** (typically `api.v1` for Magento's V1 REST resources). The general calling pattern is: const res = await api.<namespace>.<methodName>(params?, body?, requestParams?); // res.data contains the response body // res.error contains the error body (if any) Method names are generated by swagger-typescript-api and follow the pattern `<moduleCamelCase><ServiceInterface>V1<Action><Http>`. For example, the products list endpoint might be named something like `catalogProductRepositoryV1GetListGet` — but the exact name depends on the Magento version and installed modules. ### Search criteria pattern Most list endpoints accept Magento search criteria: ```ts const res = await api.v1.<listMethodName>({ searchCriteria: { filterGroups: [{ filters: [{ field: "status", value: "1", conditionType: "eq" }] }], pageSize: 10, currentPage: 1 } }); return { total: res.data?.total_count, items: res.data?.items?.map(i => i.sku) }; ``` ### Common filter conditionTypes `eq`, `neq`, `like`, `gt`, `lt`, `gteq`, `lteq`, `in`, `nin`, `notnull`, `null`, `finset`. ## Error handling Exceptions thrown in user code are caught and returned as `{ "error": "...", "stack": "..." }` with HTTP 500 inside the sandbox, then surfaced as a dict to the MCP client.