fix(netsuite): enforce provider response contracts

Author: Bill Leoutsakos

apps/docs/content/docs/en/integrations/netsuite.mdx

@@ -25,9 +25,9 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
 ## Usage notes
 
 - Record fields and supported actions vary by account, enabled features, custom records, forms, role, and permissions. Use **List Record Types** and **Get Record Metadata** before constructing create, update, upsert, action, or transform bodies. Sim intentionally accepts JSON for these dynamic record shapes instead of guessing a fixed schema.
-- Paged operations return one page only. The default limit is 100, the maximum is 1,000, and the offset must be a non-negative multiple of the limit. Sim never fetches later pages automatically. NetSuite limits ordinary collection traversal to 1,000 pages and SuiteQL queries to 100,000 results.
-- Homogeneous batch operations accept 1–100 records of one record type and always run asynchronously. Preserve the returned `location` or `jobId`, use **Get Async Status** with **Job Status** until the job completes, choose **List Tasks** to collect task IDs, check each ID with **Task Status**, then use completed IDs with **Get Async Operation Result**.
-- Sim limits each materialized request body and successful SuiteTalk response to 16 MiB. Split work into smaller pages or batches when a request or response would exceed that ceiling, even if NetSuite would otherwise accept the payload.
+- Paged operations return one page only. The default limit is 100, the maximum is 1,000, and the offset must be a non-negative multiple of the limit. Sim never fetches later pages automatically. Requests must stay within NetSuite's first 100,000 results and first 1,000 pages.
+- Homogeneous batch operations accept 1–100 records of one record type and always run asynchronously. NetSuite processes records in parallel, and individual tasks can fail independently; submission is not an all-or-none transaction. Preserve the returned `location` or `jobId`, use **Get Async Status** with **Job Status** until the job completes, choose **List Tasks** to collect task IDs, check each ID with **Task Status**, then use completed IDs with **Get Async Operation Result**. Canceling or timing out the local Sim request does not cancel a batch that NetSuite has already accepted.
+- Sim limits each materialized request body and successful SuiteTalk response to 16 MiB. Request JSON is also limited to 100 levels of nesting and 100,000 JSON values. Split work into smaller pages or batches when a request or response would exceed these ceilings, even if NetSuite would otherwise accept the payload.
 - When attaching a contact with a role, provide either the role's internal ID or external ID, not both. File attachments do not use a contact role.
 - **Attach/Detach**, homogeneous batch operations, **Get Record Form**, and **Get Select Options** require a NetSuite 2026.1-compatible account. Oracle introduced these SuiteTalk REST capabilities in [NetSuite 2026.1](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3950559.html).
 - **Get Governance Limits** returns data only for roles allowed by NetSuite; Oracle documents Administrator access for that operation.
@@ -58,7 +58,7 @@ List one page of a NetSuite record collection, optionally filtered with a q expr
 | `recordType` | string | Yes | NetSuite REST record type script ID, such as customer or salesOrder |
 | `q` | string | No | NetSuite record collection filter expression |
 | `limit` | number | No | Results to return in this page \(1-1000; default 100\) |
-| `offset` | number | No | Zero-based result offset; must be divisible by limit and select one of the first 1,000 pages |
+| `offset` | number | No | Zero-based result offset; must be divisible by limit and stay within the first 100,000 results and 1,000 pages |
 
 #### Output
 
@@ -125,7 +125,7 @@ Create a NetSuite record using the account-specific record metadata schema.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Empty for standard HTTP 204 creation; replacement creation can return the documented HTTP 201 post-state object |
 | `location` | string | Newly created record URL from the Location response header |
 
 ### NetSuite Update Record
@@ -150,7 +150,7 @@ Update fields on an existing NetSuite record with PATCH.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Empty for the documented HTTP 204 No Content response |
 | `location` | string | Updated record URL from the Location response header |
 
 ### NetSuite Upsert Record
@@ -175,7 +175,7 @@ Create or update a NetSuite record by external ID with PUT.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Empty for the documented HTTP 204 No Content response |
 
 ### NetSuite Delete Record
 
@@ -197,7 +197,7 @@ Delete one NetSuite record by internal or external ID.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Empty for the documented HTTP 204 No Content response |
 
 ### NetSuite Get Subresource
 
@@ -266,7 +266,7 @@ Retrieve valid select values for one or more fields on a new or existing record.
 | `q` | string | No | Optional select-option filter using CONTAIN, IS, or START_WITH |
 | `body` | json | No | Record fields matching the account-specific NetSuite metadata schema |
 | `limit` | number | No | Results to return in this page \(1-1000; default 100\) |
-| `offset` | number | No | Zero-based result offset; must be divisible by limit and select one of the first 1,000 pages |
+| `offset` | number | No | Zero-based result offset; must be divisible by limit and stay within the first 100,000 results and 1,000 pages |
 
 #### Output
 
@@ -343,18 +343,15 @@ Execute a supported NetSuite record action such as approve, reject, or confirm.
 | `recordType` | string | Yes | NetSuite REST record type script ID, such as customer or salesOrder |
 | `recordId` | string | Yes | NetSuite internal ID or an external-ID reference beginning with eid: |
 | `action` | string | Yes | NetSuite record action ID without the @ prefix |
-| `body` | json | No | Record fields matching the account-specific NetSuite metadata schema |
+| `body` | json | No | Parameters accepted by the selected NetSuite record action |
 
 #### Output
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
 | `data` | json | Documented NetSuite record-action response |
-|   ↳ `links` | array | Oracle HATEOAS links for the response |
-|     ↳ `rel` | string | Link relationship |
-|     ↳ `href` | string | Link target |
-|   ↳ `result` | boolean | Whether NetSuite completed the record action |
+|   ↳ `result` | boolean | True when NetSuite completed the record action |
 
 ### NetSuite Transform Record
 
@@ -378,7 +375,7 @@ Transform a supported source record into another NetSuite record type.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Empty for the documented HTTP 204 No Content response |
 
 ### NetSuite Batch Get Records
 
@@ -520,9 +517,9 @@ Execute one page of a SuiteQL query through SuiteTalk REST web services.
 | `clientId` | string | Yes | Client ID of the NetSuite OAuth 2.0 integration record |
 | `certificateId` | string | Yes | Certificate ID from OAuth 2.0 Client Credentials \(M2M\) Setup |
 | `privateKey` | string | Yes | Oracle-supported RSA \(3072/4096-bit\) or EC \(P-256/P-384/P-521\) PEM private key matching the certificate uploaded to NetSuite |
-| `query` | string | Yes | SuiteQL SELECT query |
+| `query` | string | Yes | SuiteQL SELECT query; use a complete unique ORDER BY when retrieving multiple pages |
 | `limit` | number | No | Results to return in this page \(1-1000; default 100\) |
-| `offset` | number | No | Zero-based result offset; must be divisible by limit and select one of the first 1,000 pages |
+| `offset` | number | No | Zero-based result offset; must be divisible by limit and stay within the first 100,000 results and 1,000 pages |
 
 #### Output
 
@@ -552,7 +549,7 @@ List one page of SuiteAnalytics Workbook datasets available to the authenticated
 | `certificateId` | string | Yes | Certificate ID from OAuth 2.0 Client Credentials \(M2M\) Setup |
 | `privateKey` | string | Yes | Oracle-supported RSA \(3072/4096-bit\) or EC \(P-256/P-384/P-521\) PEM private key matching the certificate uploaded to NetSuite |
 | `limit` | number | No | Results to return in this page \(1-1000; default 100\) |
-| `offset` | number | No | Zero-based result offset; must be divisible by limit and select one of the first 1,000 pages |
+| `offset` | number | No | Zero-based result offset; must be divisible by limit and stay within the first 100,000 results and 1,000 pages |
 
 #### Output
 
@@ -583,7 +580,7 @@ Execute one page of a standard or custom SuiteAnalytics Workbook dataset.
 | `privateKey` | string | Yes | Oracle-supported RSA \(3072/4096-bit\) or EC \(P-256/P-384/P-521\) PEM private key matching the certificate uploaded to NetSuite |
 | `datasetId` | string | Yes | SuiteAnalytics dataset script ID |
 | `limit` | number | No | Results to return in this page \(1-1000; default 100\) |
-| `offset` | number | No | Zero-based result offset; must be divisible by limit and select one of the first 1,000 pages |
+| `offset` | number | No | Zero-based result offset; must be divisible by limit and stay within the first 100,000 results and 1,000 pages |
 
 #### Output
 
@@ -627,6 +624,7 @@ List record types exposed to the authenticated role by the REST metadata catalog
 |     ↳ `links` | array | Oracle HATEOAS links for the response |
 |       ↳ `rel` | string | Link relationship |
 |       ↳ `href` | string | Link target |
+|       ↳ `mediaType` | string | Media type advertised for the linked metadata resource |
 
 ### NetSuite Get Record Metadata
 
@@ -674,7 +672,7 @@ Retrieve job status, list job tasks, or retrieve one task status.
 | `data` | json | Documented NetSuite asynchronous job, task collection, or task status |
 |   ↳ `completed` | boolean | Whether processing has completed |
 |   ↳ `endTime` | string | Task completion time |
-|   ↳ `id` | string | Asynchronous task ID |
+|   ↳ `id` | string | Asynchronous job or task ID |
 |   ↳ `progress` | string | Current task progress state |
 |   ↳ `startTime` | string | Task start time |
 |   ↳ `count` | number | Number of task collection entries returned |
@@ -710,7 +708,7 @@ Retrieve the provider response for one task within a completed asynchronous job.
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `status` | number | HTTP status returned by NetSuite |
-| `data` | json | NetSuite response body; record fields are account-specific and dynamic |
+| `data` | json | Result payload for the submitted asynchronous operation; record fields are account-specific and dynamic |
 
 ### NetSuite Get Server Time
 

apps/sim/blocks/blocks/netsuite.test.ts

@@ -248,7 +248,7 @@ describe('Oracle NetSuite block', () => {
       enabled: true,
       generationType: 'sql-query',
     })
-    for (const field of ['fields', 'ids', 'replace']) {
+    for (const field of ['fields', 'ids']) {
       expect(getSubBlock(field).wandConfig?.prompt, field).toContain(
         'no explanations, no extra text'
       )
@@ -424,6 +424,7 @@ describe('Oracle NetSuite block', () => {
       condition: { field: 'operation', value: 'netsuite_get_async_status' },
     })
     expect(getSubBlock('view').value?.({})).toBe('job')
+    expect(getSubBlock('replace')).not.toHaveProperty('wandConfig')
   })
 
   it('ships the seven practical templates and five focused skills in the agreed scope', () => {

apps/sim/blocks/blocks/netsuite.ts

@@ -433,7 +433,7 @@ Return ONLY the comma-separated field IDs - no explanations, no extra text.`,
     },
     {
       id: 'body',
-      title: 'Record Fields (JSON)',
+      title: 'Request Body (JSON)',
       type: 'code',
       language: 'json',
       placeholder: '{"companyName":"Acme Inc."}',
@@ -653,7 +653,7 @@ Return ONLY the SuiteQL query - no explanations, no markdown, no extra text.`,
       id: 'offset',
       title: 'Offset',
       type: 'short-input',
-      placeholder: '0 (multiple of limit; first 1000 pages)',
+      placeholder: '0 (multiple of limit; first 100,000 results)',
       condition: { field: 'operation', value: PAGING_OPERATIONS },
       mode: 'advanced',
     },
@@ -688,13 +688,6 @@ Return ONLY the SuiteQL query - no explanations, no markdown, no extra text.`,
         value: ['netsuite_create_record', 'netsuite_update_record', 'netsuite_upsert_record'],
       },
       mode: 'advanced',
-      wandConfig: {
-        enabled: true,
-        prompt: `Generate a comma-separated list of NetSuite sublist script IDs to replace from the user's request.
-
-Return ONLY the comma-separated sublist IDs - no explanations, no extra text.`,
-        placeholder: 'Describe the sublists to replace',
-      },
     },
     {
       id: 'idempotencyKey',
@@ -813,7 +806,10 @@ Return ONLY the comma-separated sublist IDs - no explanations, no extra text.`,
     externalId: { type: 'string', description: 'External ID used for upsert' },
     q: { type: 'string', description: 'Record or select-option filter expression' },
     fields: { type: 'string', description: 'Comma-separated field IDs' },
-    body: { type: 'json', description: 'Account-specific record fields' },
+    body: {
+      type: 'json',
+      description: 'Account-specific record fields or parameters for a selected record action',
+    },
     subresourcePath: { type: 'string', description: 'Record subresource path' },
     relatedType: { type: 'string', description: 'Related contact or file type' },
     relatedId: {
@@ -835,7 +831,8 @@ Return ONLY the comma-separated sublist IDs - no explanations, no extra text.`,
     limit: { type: 'number', description: 'Page size (1-1000)' },
     offset: {
       type: 'number',
-      description: 'Page offset divisible by limit and within the first 1000 pages',
+      description:
+        'Page offset divisible by limit and within the first 100,000 results and 1,000 pages',
     },
     expand: { type: 'string', description: 'Resources to expand' },
     expandSubResources: { type: 'boolean', description: 'Expand sublists and subrecords' },

apps/sim/tools/generated/tool-metadata.ts

@@ -98,6 +98,7 @@ export const netsuiteAttachRecordTool: ToolConfig<NetSuiteAttachParams, NetSuite
             { value: relatedType, label: 'Related type' },
             { value: params.relatedId, label: 'Related ID' }
           ),
+          success: { status: 204, body: 'none' },
           body: roleId
             ? { role: { id: roleId } }
             : roleExternalId

apps/sim/tools/generated/tool-outputs.ts

@@ -69,6 +69,7 @@ export const netsuiteBatchDeleteRecordsTool: ToolConfig<
         return {
           method: 'DELETE',
           path: buildRecordPath({ value: params.recordType, label: 'Record type' }),
+          success: { status: 202, body: 'none' },
           responseLocation: 'async-job',
           query: { ids: normalizeBatchIds(params.ids) },
           headers: {

apps/sim/tools/netsuite/attach_record.ts

@@ -85,6 +85,7 @@ export const netsuiteBatchGetRecordsTool: ToolConfig<NetSuiteBatchGetParams, Net
         return {
           method: 'GET',
           path: buildRecordPath({ value: params.recordType, label: 'Record type' }),
+          success: { status: 202, body: 'none' },
           responseLocation: 'async-job',
           query: {
             expandRecords: true,

apps/sim/tools/netsuite/batch_delete_records.ts

@@ -48,7 +48,7 @@ export const netsuiteCreateRecordTool: ToolConfig<NetSuiteCreateRecordParams, Ne
     replace: {
       type: 'string',
       required: false,
-      visibility: 'user-or-llm',
+      visibility: 'user-only',
       description: 'Comma-separated sublists whose default lines should be replaced',
     },
   },
@@ -59,6 +59,10 @@ export const netsuiteCreateRecordTool: ToolConfig<NetSuiteCreateRecordParams, Ne
       () => ({
         method: 'POST',
         path: buildRecordPath({ value: params.recordType, label: 'Record type' }),
+        success: [
+          { status: 201, body: 'object' },
+          { status: 204, body: 'none' },
+        ],
         responseLocation: 'resource',
         query: { replace: optionalTrim(params.replace, 'Replace sublists') },
         body: params.body,
@@ -69,7 +73,8 @@ export const netsuiteCreateRecordTool: ToolConfig<NetSuiteCreateRecordParams, Ne
     status: { type: 'number', description: 'HTTP status returned by NetSuite' },
     data: {
       type: 'json',
-      description: 'NetSuite response body; record fields are account-specific and dynamic',
+      description:
+        'Empty for standard HTTP 204 creation; replacement creation can return the documented HTTP 201 post-state object',
       nullable: true,
     },
     location: {

apps/sim/tools/netsuite/batch_get_records.ts

@@ -56,14 +56,15 @@ export const netsuiteDeleteRecordTool: ToolConfig<NetSuiteDeleteRecordParams, Ne
           { value: params.recordType, label: 'Record type' },
           { value: params.recordId, label: 'Record ID' }
         ),
+        success: { status: 204, body: 'none' },
       }),
       signal
     ),
   outputs: {
     status: { type: 'number', description: 'HTTP status returned by NetSuite' },
     data: {
       type: 'json',
-      description: 'NetSuite response body; record fields are account-specific and dynamic',
+      description: 'Empty for the documented HTTP 204 No Content response',
       nullable: true,
     },
   },