gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/netsuite/handlers.py

@@ -0,0 +1,32 @@
+"""NetSuite world tools; every mutation goes through the schema store.
+
+Failures carry the REST web services error codes NetSuite documents for the
+same conditions (section_156570709583: "Error Handling in REST Web Services").
+"""
+
+from gateway_env import store, tool
+
+
+@tool(name="get_customer")
+def get_customer(id):
+    customer = store.get("netsuite_customers", {"id": id})
+    if customer is None:
+        raise ValueError("NONEXISTENT_ID: Record does not exist.")
+    return customer
+
+
+@tool(name="list_sales_orders")
+def list_sales_orders(entity=None):
+    orders = store.list("netsuite_sales_orders")
+    return [order for order in orders if entity is None or order.get("entity", {}).get("id") == entity]
+
+
+@tool(name="create_sales_order")
+def create_sales_order(order):
+    entity_id = order.get("entity", {}).get("id")
+    if entity_id is None or store.get("netsuite_customers", {"id": entity_id}) is None:
+        raise ValueError(
+            "INVALID_CONTENT: Error while accessing resource: You have entered an "
+            f"Invalid Field Value {entity_id} for the following field: entity"
+        )
+    return store.insert("netsuite_sales_orders", order, source={"record": "tool.create_sales_order"})

gatewaysdk/environment/schema/connectors/netsuite/parity.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "connector": "netsuite",
+  "status": "subset",
+  "world_tools": ["create_sales_order", "get_customer", "list_sales_orders"],
+  "registration": {
+    "mode": "managed",
+    "provider": "merge",
+    "managed_tool_allowlist": [
+      "create_sales_order",
+      "get_customer",
+      "list_sales_orders"
+    ]
+  },
+  "surfaces": [
+    {
+      "name": "NetSuite AI Connector Service",
+      "kind": "official_tenant_mcp",
+      "auth": "NetSuite account and role authentication",
+      "manifest_validation": "credential_required",
+      "supported_world_tools": [
+        "create_sales_order",
+        "get_customer",
+        "list_sales_orders"
+      ],
+      "limitations": [
+        "The endpoint and tool manifest are account- and role-specific.",
+        "Oracle standard tool names are not exact matches for every world tool."
+      ],
+      "evidence": [
+        "https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_143403258.html"
+      ]
+    },
+    {
+      "name": "Merge Agent Handler",
+      "kind": "managed_provider",
+      "auth": "Merge managed connection",
+      "manifest_validation": "public_catalog",
+      "supported_world_tools": [
+        "create_sales_order",
+        "get_customer",
+        "list_sales_orders"
+      ],
+      "limitations": [
+        "Gateway exposes only the three exact schema-world tool matches."
+      ],
+      "evidence": ["https://docs.merge.dev/agent-handler/overview/"]
+    }
+  ]
+}

gatewaysdk/environment/schema/connectors/netsuite/provenance.json

@@ -0,0 +1,137 @@
+{
+  "slug": "netsuite",
+  "shape": "tenant-shaped",
+  "label": "subset",
+  "label_reasons": [
+    "This is an unbound standard-record skeleton. NetSuite metadata is role- and account-personalized; describe-on-bind is required for an actual tenant.",
+    "No SuiteCloud Developer Network account or consenting sandbox was available, so no per-account metadata catalog, vendor round trip, or golden replay ran.",
+    "The model covers nine brief-scoped records, not the hundreds of record/v1 resources exposed by NetSuite.",
+    "The retired public 2023.2 API Browser is pinned through an exact Internet Archive raw snapshot; it is vendor-generated evidence but is not a tenant overlay."
+  ],
+  "source": [
+    {
+      "kind": "vendor-schema-browser",
+      "role": "primary",
+      "name": "NetSuite REST API Browser: Record API v1",
+      "origin_url": "https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.2/index.html",
+      "archive_url": "https://web.archive.org/web/20240714132010id_/https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.2/index.html",
+      "version": "2023.2",
+      "bytes": 20904488,
+      "sha256": "2b7c89cd3c9576acd9a963ab10fbcc397cc37f48e8650866ea9f12e09654e550",
+      "used_for": "All nine record definitions, nested local sublists/subrecords, property names and types, reference alternatives, and declared itemType/salesOrder.status/invoice.status value blocks. Enum order is retained verbatim."
+    },
+    {
+      "kind": "vendor-schema-browser",
+      "role": "enum-cross-check",
+      "name": "NetSuite REST API Browser 2024.2 salesOrder chunk 13",
+      "url": "https://web.archive.org/web/20260317224254id_/https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2024.2/chunks/data13.part",
+      "version": "2024.2",
+      "bytes": 1048576,
+      "sha256": "21c855eef7f4d01b4bf438cff76b4a0acf2883b7d030b308ea24a63ec0426a19",
+      "used_for": "Re-verifying the declared salesOrder.status id values A through H."
+    },
+    {
+      "kind": "vendor-docs",
+      "role": "supporting",
+      "name": "Working with Resource Metadata",
+      "url": "https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_1540810168.html",
+      "version": "NetSuite Applications Suite help retrieved 2026-09-06",
+      "bytes": 11103,
+      "sha256": "c613eafc5cbea76486db4266f427c2e416a054082dcae4f80dbb965026c9cc80",
+      "used_for": "Personalized dynamic-schema and describe-on-bind requirements."
+    },
+    {
+      "kind": "vendor-docs",
+      "role": "supporting",
+      "name": "Working with JSON Schema Metadata",
+      "url": "https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1545129726.html",
+      "version": "NetSuite Applications Suite help retrieved 2026-09-06",
+      "bytes": 9331,
+      "sha256": "79ba870861a741fb637a74ab4e8a1557f839b774714793941ef12453595c03bf",
+      "used_for": "JSON Schema media type, nested record structure, and tenant custom-field behavior."
+    },
+    {
+      "kind": "vendor-docs",
+      "role": "supporting",
+      "name": "Error Handling in REST Web Services",
+      "url": "https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156570709583.html",
+      "version": "NetSuite Applications Suite help retrieved 2026-09-06",
+      "bytes": 15074,
+      "sha256": "e9b09f930fac15efacfb8b3093458e90f35f9d18088b8172906a16ebe27f26d3",
+      "used_for": "Error envelope and handler error-code examples."
+    }
+  ],
+  "authored_by": "connector-template-author; deterministic transcription of pinned API Browser declarations",
+  "importer": null,
+  "scope_hash": "sha256:508371c71eb2b3c76e00cdd1160a7aabaf96e572ae4cf659c900d662b05dcc81",
+  "world_sha256": "sha256:3aad6b303e21660425e8c8d889ce9c6c166fc23fe617cca9bb4c5cb7ffc74118",
+  "generated_at": "2026-09-06T22:27:40Z",
+  "coverage": {
+    "entities": 9,
+    "recursive_fields": 5259,
+    "counting_method": "For each x-gateway entity schema, count every object property and recursively resolve local $ref; descend properties, array items, allOf, anyOf, and oneOf. References are counted at every occurrence; base.json primitives contribute zero properties.",
+    "reconstruction_target": 1958,
+    "target_note": "The prior measurement is not reproduced because correcting the prior flattened-reference and bare-sublist shapes increases the evidence-backed recursive count to 5259. No fields were added merely to meet a number.",
+    "record_property_policy": "All properties in the nine pinned browser record definitions are retained. Local record-prefixed definitions are recursively retained; out-of-scope record references use the finite vendor nsResource shape."
+  },
+  "tenant_channel": {
+    "required": true,
+    "method": "describe-on-bind",
+    "call": "GET /services/rest/record/v1/metadata-catalog/{record} with Accept: application/schema+json against the bound account and role",
+    "status": "not run; no tenant credentials or sandbox were available",
+    "supplies": [
+      "enabled standard records and role-visible fields",
+      "customrecord* resources",
+      "custentity*, custbody*, custcol*, and custitem* fields",
+      "custom lists and custom segments",
+      "account-specific enum additions and nullable/required declarations"
+    ]
+  },
+  "fidelity_corrections": [
+    "Record and enum references remain nested link objects; they are no longer flattened to scalar ids.",
+    "salesOrder.item and every other in-scope local sublist retain the vendor collection wrapper (count, hasMore, items, links, offset, totalResults).",
+    "salesOrder.item remains nested even though salesOrder-itemElement is also projected as netsuite_sales_order_lines for keyable line-level tasks.",
+    "Only entity key fields are required. The browser declares no record-schema required list, so the brief-derived required lists were removed.",
+    "Undeclared business uniqueness constraints were removed. Sparse optional uniqueness is supported, but constraints are not invented when the vendor schema does not declare them.",
+    "Polymorphic entity, item, and createdFrom references are no longer narrowed to one local entity type.",
+    "acctType is not emitted as a closed enum: the reverified 2023.2 primary declaration has no value block for it. A bound account catalog must supply its values.",
+    "itemType and transaction status are object-valued enums whose id property carries the vendor-declared values; refName remains available."
+  ],
+  "requiredness": {
+    "vendor_declaration": "No required property markers occur after the API Browser Schema Definitions heading; required markers in the artifact belong to operation path parameters.",
+    "compiler_forced": [
+      "Each entity id is required and non-null because gateway-world/1 requires primary keys to be required direct scalar properties.",
+      "netsuite_sales_order_lines.order_id and line are required because they form its projected composite key."
+    ],
+    "endpoint_sections": "Not applicable: this template models record resources, not endpoint response envelopes. Nested collection section properties remain optional as declared."
+  },
+  "nullability": {
+    "status": "not asserted where the browser omits nullable metadata",
+    "gap": "Oracle documents that account metadata may include nullable, but the pinned API Browser renderer does not expose nullable markers. A tenant JSON Schema response is required to distinguish null from omission without guessing."
+  },
+  "compiler_limitations": [
+    "Nested scalar subsidiary references are enforced for customers, vendors, and journal entries. Polymorphic references and collection-item paths remain unenforced.",
+    "Recursive expansion of every external record reference is forbidden, so out-of-scope references terminate at nsResource.",
+    "Optional business identifiers carry no unique constraints because the pinned schema does not declare them.",
+    "NetSuite date and date-time fields retain their respective gateway-world/1 formats."
+  ],
+  "error_format": {
+    "envelope": "{\"type\", \"title\", \"status\", \"o:errorDetails\": [{\"detail\", \"o:errorCode\"}]}",
+    "codes_modelled": [
+      "NONEXISTENT_ID",
+      "INVALID_CONTENT"
+    ],
+    "limitation": "Handlers raise code-bearing ValueError strings; the mock-tools handler API does not return HTTP problem-detail envelopes."
+  },
+  "verification": {
+    "schema_compile": "python -m gatewaysdk.environment.schema compile /home/ubuntu/netsuite-connector-verify: pass; status ok; domain hash e0b463952ab43c3d8dca4ca0c45e92b95b451571ba2f5dda67c18d27e8c8b36b",
+    "schema_check": "python -m gatewaysdk.environment.schema check /home/ubuntu/netsuite-connector-verify: pass; status ok; domain hash e0b463952ab43c3d8dca4ca0c45e92b95b451571ba2f5dda67c18d27e8c8b36b",
+    "sandbox": "skipped: SuiteCloud Developer Network partner account not provisioned",
+    "tenant_overlay": "skipped: no bound account metadata catalog",
+    "goldens": "skipped: no sandbox capture; no customer data included",
+    "schema_init": "python -m gatewaysdk.environment.schema init /home/ubuntu/netsuite-connector-verify --connector netsuite: pass; status ok; domain hash e0b463952ab43c3d8dca4ca0c45e92b95b451571ba2f5dda67c18d27e8c8b36b"
+  },
+  "not_shipped": [
+    "suiteql: gateway_env.store does not expose query to handlers, raw SQL in handlers is forbidden, and SuiteQL identifiers are not this world store schema."
+  ]
+}

gatewaysdk/environment/schema/connectors/netsuite/scope.toml

@@ -0,0 +1,78 @@
+# NetSuite is tenant-shaped. This file scopes the shared, unbound skeleton only.
+# A bound account's metadata catalog remains authoritative for enabled standard
+# records, custom records, custom fields, custom lists, and custom segments.
+
+[source]
+kind = "vendor-schema-browser"
+record_api = "record/v1"
+version = "2023.2"
+origin = "https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.2/index.html"
+archived_snapshot = "https://web.archive.org/web/20240714132010id_/https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.2/index.html"
+importer = "none; API Browser schema definitions transcribed deterministically"
+
+[coverage]
+shape = "tenant-shaped"
+label = "subset"
+entity_count = 9
+recursive_field_count = 5259
+record_schema_requiredness = "The API Browser declares no required properties in record schema definitions. Only primary-key fields are required here because gateway-world/1 requires entity keys to be required and non-null."
+reference_policy = "Record references retain their nested link-object form. Local sublists and subrecords are recursively modelled; references to records outside this nine-entity scope use the declared nsResource shape."
+
+[entities]
+netsuite_subsidiaries = "subsidiary"
+netsuite_accounts = "account"
+netsuite_customers = "customer"
+netsuite_vendors = "vendor"
+netsuite_items = "inventoryItem"
+netsuite_sales_orders = "salesOrder, including the nested item collection"
+netsuite_sales_order_lines = "salesOrder-itemElement projected as a separately keyable entity"
+netsuite_invoices = "invoice, including nested sublists and subrecords"
+netsuite_journal_entries = "journalEntry, including the nested line collection"
+
+[keys]
+netsuite_sales_order_lines = { primary_key = ["order_id", "line"], reason = "The vendor line has `line` but no parent field because REST nests it under salesOrder.item.items. `order_id` is the sole synthetic containment field. The salesOrder entity still retains the vendor's nested item collection." }
+
+[unique]
+# None. The vendor schema does not declare these optional record properties as
+# JSON Schema uniqueness constraints. Sparse optional uniqueness is supported,
+# but business-number uniqueness must not be inferred.
+
+[relationships]
+"netsuite_sales_order_lines.order_id" = "netsuite_sales_orders"
+"netsuite_customers./subsidiary/id" = "netsuite_subsidiaries"
+"netsuite_vendors./subsidiary/id" = "netsuite_subsidiaries"
+"netsuite_journal_entries./subsidiary/id" = "netsuite_subsidiaries"
+
+[relationships.not_declared]
+"netsuite_sales_orders.entity.id" = "Polymorphic nested reference; the catalog permits customer, partner, vendor, nsResource, employee, or contact."
+"netsuite_sales_order_lines.item.id" = "Polymorphic nested item reference; the catalog declares multiple item record alternatives."
+"netsuite_invoices.entity.id" = "Polymorphic nested reference; not narrowed to customer."
+"netsuite_invoices.createdFrom.id" = "Generic nsResource transaction reference; not narrowed to salesOrder."
+"netsuite_journal_entries.line.items[].account.id" = "The path traverses a collection and cannot be reduced to one scalar foreign key."
+
+[polymorphic]
+"netsuite_sales_orders.entity" = ["customer", "partner", "vendor", "nsResource", "employee", "contact"]
+"netsuite_invoices.entity" = ["customer", "partner", "vendor", "nsResource", "employee", "contact"]
+"netsuite_invoices.createdFrom" = ["nsResource"]
+"netsuite_sales_order_lines.item" = ["inventoryItem", "assemblyItem", "kitItem", "nsResource", "discountItem", "markupItem", "subtotalItem", "descriptionItem", "paymentItem", "salesTaxItem", "shipItem", "downloadItem", "giftCertificateItem", "subscriptionPlan", "nonInventorySaleItem", "nonInventoryResaleItem", "nonInventoryPurchaseItem", "serviceSaleItem", "serviceResaleItem", "servicePurchaseItem", "otherChargeSaleItem", "otherChargeResaleItem", "otherChargePurchaseItem"]
+
+[compiler_limitations]
+nested_relationships = "Nested scalar reference ids can be key-enforced; polymorphic references and paths through collection items remain unenforced."
+nullable_unique = "Sparse optional uniqueness is supported, but no optional NetSuite business number is constrained because the pinned schema does not declare its uniqueness."
+date_format = "Vendor `date` fields use format date; vendor date-time fields retain format date-time."
+external_reference_cycles = "Expanding every referenced record would create recursive schemas, which gateway-world/1 rejects. Out-of-scope record references therefore use the finite nsResource link shape."
+
+[exclusions]
+other_records = "The browser exposes hundreds of record resources. This skeleton is limited to the nine entities named in the connector brief; purchase orders, bills, fulfillments, payments, employees, currencies, locations, and other masters remain external references."
+tenant_overlay = "No account metadata catalog was available. customrecord*, custentity*, custbody*, custcol*, custitem*, custom lists, custom segments, enabled-feature changes, and account-specific enum additions require describe-on-bind."
+operation_contracts = "The entity model transcribes record schema definitions, not HTTP headers, query parameters, pagination endpoints, async task endpoints, or governance behavior."
+
+[sandbox]
+required = true
+available = false
+requirement = "SuiteCloud Developer Network partner account or a consenting NetSuite sandbox with a role-scoped REST Web Services connection."
+blocked_verification = ["per-account metadata overlay", "vendor round trip", "captured synthetic goldens", "tenant enum drift check"]
+
+[fixture]
+shipped = false
+reason = "The connector template layout does not support data files; scaffold initialization writes empty data. No customer or vendor response data is included."