@celigo/api-specs 0.2.27 → 0.2.29

package/dist/bartendertemplate.yml

@@ -0,0 +1,508 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: BarTender Templates
+  description: API for listing and downloading Celigo-published BarTender label templates used by EDI label-printing flows.
+  x-celigo-ai-guidance:
+    - |-
+      Call `GET /v1/bartenderTemplates` first — that returns unique published
+      `names` only. Then call `GET /v1/bartenderTemplates?name=<selected>` to
+      load `s3Key` values and `fieldMappings` for the chosen templates. Download
+      a `.btw` with `GET /v1/bartenderTemplates/{name}/download`. Requires EDI
+      and EDI label-printing entitlements; returns 422
+      `edi_subscription_required` when either is missing and a bare 404 (empty
+      body) when the global label-printing kill switch is active.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: BarTender Templates
+    description: |-
+      Celigo-published BarTender (`.btw`) label templates synced daily from
+      BarTender Cloud. List unique names, load selected template details and
+      lookup-cache field mappings, or download a published `.btw`.
+
+      Requires a standard integrator.io JWT with manage or monitor role, plus
+      EDI and EDI label-printing entitlements on the account.
+
+      ## BarTender template schemas
+
+      {% openapi-schemas spec="bartendertemplate" schemas="BarTenderTemplateCatalog,BarTenderTemplate,BarTenderFieldMapping" grouped="true" %}
+paths:
+  /v1/bartenderTemplates:
+    get:
+      x-internal: false
+      operationId: listBarTenderTemplates
+      tags:
+        - BarTender Templates
+      summary: List BarTender label templates
+      description: |-
+        Returns Celigo-published BarTender catalog data. The catalog is read from
+        S3 (`catalog.json`, written by the daily sync cron) and cached in-process.
+
+        Omit `name` to get unique published template names (sorted). Pass one or
+        more `name` values to get matching templates and lookup-cache field
+        mappings plus the catalog `syncedAt`.
+
+        `name` accepts a comma-separated list or repeated query parameters.
+        Matching is case-sensitive and also treats pipe-separated tokens as
+        aliases (`amazon | 133` matches `amazon` or `133`). Unknown names return
+        empty `templates` and `fieldMappings` — not 404. `limit`, `page`, and
+        `search` are ignored.
+      parameters:
+        - name: name
+          in: query
+          required: false
+          description: |-
+            Filter to these published template names. Comma-separated or
+            repeated (`?name=amazon&name=walmart`). When omitted or empty, the
+            response is `{ names }` only.
+          schema:
+            type: string
+            examples:
+              - amazon
+              - amazon,walmart
+      responses:
+        '200':
+          description: |-
+            Unique names when `name` is omitted; filtered catalog details when
+            `name` is provided.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BarTenderTemplateCatalog'
+              examples:
+                names:
+                  summary: Unique published names (no name query)
+                  value:
+                    names:
+                      - amazon
+                      - walmart
+                details:
+                  summary: Filtered templates and field mappings
+                  value:
+                    syncedAt: '2026-07-10T02:15:00.000Z'
+                    templates:
+                      - name: amazon
+                        s3Key: EDI_BarTender_Templates/templates/FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw
+                    fieldMappings:
+                      - key: amazon
+                        value:
+                          configurations:
+                            PACK|*:
+                              templateName: AMAZON_US_RETAIL_CARTON
+                      - key: amazon | 133
+                        value:
+                          configurations:
+                            PALLET|*:
+                              templateName: AMAZON_US_RETAIL_PALLET
+                empty_names:
+                  summary: Catalog has no published templates
+                  value:
+                    names: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The global BarTender label-printing kill switch
+            (`BARTENDER_LABEL_PRINTING_DISABLED`) is active. The route responds
+            with a bare `404` and an empty body so the feature appears unavailable.
+        '422':
+          description: |-
+            The account lacks a required EDI entitlement. Missing `edi.enabled` or
+            `edi.labelPrinting.enabled` both return the same
+            `edi_subscription_required` error — the route reuses the standard EDI
+            license gate used by other B2B Manager endpoints.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                edi_not_enabled:
+                  summary: EDI is not enabled on the account
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+                label_printing_not_enabled:
+                  summary: EDI label printing is not enabled on the account
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '502':
+          description: |-
+            The catalog could not be read from S3 or the stored `catalog.json` is
+            malformed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_unavailable:
+                  summary: S3 read or parse failure
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_UNAVAILABLE
+                        message: The BarTender template catalog is temporarily unavailable. Please try again later.
+        '503':
+          description: |-
+            The catalog has never been published for this environment, or the
+            EDI license check could not be completed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_not_initialized:
+                  summary: Catalog not yet synced
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_NOT_INITIALIZED
+                        message: The BarTender template catalog has not been published yet. Please try again later.
+                license_check_failed:
+                  summary: EDI license lookup failed
+                  value:
+                    errors:
+                      - code: edi_license_check_failed
+                        message: We're unable to verify your EDI license at the moment. Please contact support if the issue persists.
+  /v1/bartenderTemplates/{name}/download:
+    get:
+      x-internal: false
+      operationId: downloadBarTenderTemplate
+      tags:
+        - BarTender Templates
+      summary: Download a BarTender label template
+      description: |-
+        Returns the published `.btw` binary for the named template.
+
+        `name` must match a published catalog entry exactly — pipe-token alias
+        matching from the list route is not applied here. The file is streamed
+        as `application/octet-stream` with `Content-Disposition: attachment`.
+      x-celigo-ai-guidance:
+        - |-
+          The name check runs before the catalog lookup, so a published name that
+          contains characters outside `[A-Za-z0-9._ -]` (parentheses, for example)
+          appears in the list response but answers 400
+          BARTENDER_TEMPLATE_INVALID_NAME here and cannot be downloaded through this
+          route. Live-verified 2026-09-18.
+      parameters:
+        - name: name
+          in: path
+          required: true
+          description: |-
+            Published template name from `GET /v1/bartenderTemplates`. Allowed
+            characters are letters, digits, period, underscore, space, and
+            hyphen; `..` is rejected.
+          schema:
+            type: string
+            pattern: ^[A-Za-z0-9._ -]+$
+            examples:
+              - amazon
+      responses:
+        '200':
+          description: Published `.btw` binary.
+          headers:
+            Content-Disposition:
+              description: |-
+                Attachment filename taken from the template object's basename
+                (the `.btw` file name).
+              schema:
+                type: string
+                examples:
+                  - attachment; filename="FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw"
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          description: |-
+            `name` is empty or contains characters outside
+            `[A-Za-z0-9._ -]`, or includes `..`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_name:
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_INVALID_NAME
+                        message: The BarTender template name is invalid.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The template is not in the published catalog, or the global
+            label-printing kill switch is active (bare `404`, empty body).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Name is not a published template
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_NOT_FOUND
+                        message: The requested BarTender template was not found in the published catalog.
+        '422':
+          description: |-
+            The account lacks a required EDI entitlement. Missing `edi.enabled` or
+            `edi.labelPrinting.enabled` both return `edi_subscription_required`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                edi_subscription_required:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '502':
+          description: |-
+            The catalog could not be read, or the `.btw` object could not be
+            fetched from S3.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_unavailable:
+                  summary: Catalog read or parse failure
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_UNAVAILABLE
+                        message: The BarTender template catalog is temporarily unavailable. Please try again later.
+                download_failed:
+                  summary: Template object read failure
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_DOWNLOAD_FAILED
+                        message: The BarTender template file is temporarily unavailable. Please try again later.
+        '503':
+          description: |-
+            The catalog has never been published for this environment, or the
+            EDI license check could not be completed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_not_initialized:
+                  summary: Catalog not yet synced
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_NOT_INITIALIZED
+                        message: The BarTender template catalog has not been published yet. Please try again later.
+                license_check_failed:
+                  summary: EDI license lookup failed
+                  value:
+                    errors:
+                      - code: edi_license_check_failed
+                        message: We're unable to verify your EDI license at the moment. Please contact support if the issue persists.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    BarTenderTemplate:
+      type: object
+      description: |-
+        One published BarTender label template. Internal catalog fields (`id`,
+        `btChecksum`, `modifiedDateTime`, `version`) are not exposed — only `name`
+        and `s3Key` are returned.
+      required:
+        - name
+        - s3Key
+      properties:
+        name:
+          type: string
+          description: |-
+            Published display name, derived from the `.btw` file stem
+            (`amazon.btw` → `"amazon"`). Use this value in the `name` query
+            parameter and in `GET /v1/bartenderTemplates/{name}/download`.
+          examples:
+            - amazon
+        s3Key:
+          type: string
+          description: |-
+            Object key for the `.btw` binary in the UI-resources bucket. Pass this
+            to the downstream S3 export step that pushes the template to the
+            customer's BarTender environment.
+          examples:
+            - EDI_BarTender_Templates/templates/FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw
+    BarTenderFieldMapping:
+      type: object
+      description: |-
+        One lookup-cache field mapping from the published catalog. Keys often
+        name a template (or a pipe-separated alias such as `amazon | 133`);
+        values keep whatever JSON shape the master cache stored.
+      required:
+        - key
+        - value
+      properties:
+        key:
+          type: string
+          description: |-
+            Mapping key. Filtered with the same case-sensitive exact / pipe-token
+            match as template `name` when `name` is supplied on the list route.
+          examples:
+            - amazon
+            - amazon | 133
+            - carrier
+        value:
+          description: |-
+            Mapping value from the master lookup cache. May be a string or an
+            object; consumers should check the runtime type before use.
+          oneOf:
+            - title: String value
+              type: string
+            - title: Object value
+              type: object
+              additionalProperties: true
+          examples:
+            - UPS
+            - configurations:
+                PACK|*:
+                  templateName: AMAZON_US_RETAIL_CARTON
+    BarTenderTemplateCatalog:
+      type: object
+      description: |-
+        Response from `GET /v1/bartenderTemplates`. When `name` is omitted the
+        body is `{ names }`. When `name` is provided the body is
+        `{ syncedAt, templates, fieldMappings }` for the matching entries.
+      properties:
+        names:
+          type: array
+          description: |-
+            Unique published template names, sorted. Present when `name` is
+            omitted. An empty catalog returns `[]`.
+          items:
+            type: string
+          examples:
+            - - amazon
+              - walmart
+        syncedAt:
+          type: string
+          format: date-time
+          description: |-
+            UTC timestamp of the last successful catalog sync. Present when
+            `name` is provided.
+          examples:
+            - '2026-07-10T02:15:00.000Z'
+        templates:
+          type: array
+          description: |-
+            Published templates whose `name` matches any requested `name` value.
+            Present when `name` is provided. Unknown names yield an empty array,
+            not a 404.
+          items:
+            $ref: '#/components/schemas/BarTenderTemplate'
+        fieldMappings:
+          type: array
+          description: |-
+            Published lookup-cache mappings whose `key` matches any requested
+            `name` value. Present when `name` is provided. A catalog that predates
+            field-mapping sync returns `[]`.
+          items:
+            $ref: '#/components/schemas/BarTenderFieldMapping'
+      if:
+        required:
+          - names
+      then:
+        required:
+          - names
+      else:
+        required:
+          - syncedAt
+          - templates
+          - fieldMappings
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+x-enable-proxy: true
+x-internal: false

package/dist/connection.yml

@@ -1828,6 +1828,91 @@ paths:
                             - 64ff4b21612a134bd2f45534
         '401':
           $ref: '#/components/responses/401-unauthorized'
+  /v1/connections/{_id}/distributedApps:
+    get:
+      x-internal: false
+      summary: Check the Celigo SuiteApp and bundle on a NetSuite connection
+      description: |-
+        Reports, live from the connected NetSuite account, whether the Celigo integrator.io SuiteApp
+        (SuiteScript 2.x) and the legacy Celigo bundle are installed — the check the UI runs before
+        offering a NetSuite API version that depends on either. Round-trips to NetSuite, so expect a
+        few seconds. Only connections of type `netsuite` are accepted.
+
+        Use this instead of the connection's `netsuite.suiteAppInstalled`, which reflects only the
+        SuiteApp as detected the last time the connection authenticated.
+      operationId: getConnectionDistributedApps
+      tags:
+        - Connections
+      parameters:
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+          description: NetSuite connection to check.
+      responses:
+        '200':
+          description: Installation state of each component.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - bundle
+                  - suiteapp
+                properties:
+                  bundle:
+                    description: The legacy Celigo integrator.io bundle (SuiteScript 1.0).
+                    allOf:
+                      - $ref: '#/components/schemas/DistributedAppStatus'
+                  suiteapp:
+                    description: The Celigo integrator.io SuiteApp (SuiteScript 2.x).
+                    allOf:
+                      - $ref: '#/components/schemas/DistributedAppStatus'
+              examples:
+                both_installed:
+                  summary: SuiteApp and bundle both present
+                  value:
+                    bundle:
+                      success: true
+                    suiteapp:
+                      success: true
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No connection found for the given `_id`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Connection not found for the given id.
+        '422':
+          description: The connection exists but is not a NetSuite connection.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_connection_type:
+                  value:
+                    errors:
+                      - message: 'invalid connection type: http'
+      x-celigo-ai-guidance:
+        - |-
+          Decides the NetSuite import adaptor: when `suiteapp.success` or `bundle.success` is true,
+          author a NetSuiteDistributedImport (netsuite_da) — Celigo RESTlets; when both are false,
+          author a NetSuiteHTTPImport (NetSuite REST APIs). Exports and lookups do not depend on this
+          check — NetSuiteHTTPExport needs neither component.
+        - |-
+          A non-NetSuite connection answers 422 with the message "invalid connection type: <type>"
+          and no `code`; an unknown `_id` answers 404 `invalid_ref`.
   /v1/salesforce/metadata/connections/{_id}/sObjectTypes:
     get:
       x-internal: false
@@ -7315,7 +7400,11 @@ components:
                     suiteAppInstalled:
                       type: boolean
                       readOnly: true
-                      description: When true, the Celigo SuiteApp bundle is installed in the connected NetSuite account. Detected by the server when the connection authenticates to NetSuite.
+                      description: |-
+                        When true, the Celigo integrator.io SuiteApp (SuiteScript 2.x) was detected in
+                        the connected NetSuite account the last time the connection authenticated. It
+                        says nothing about the legacy Celigo bundle; for a live check of both, use
+                        `GET /v1/connections/{_id}/distributedApps`.
             salesforce:
               description: Present when `type` is `salesforce`.
               allOf:
@@ -8463,6 +8552,19 @@ components:
             dependencyIds:
               export:
                 - 64ff4b21612a134bd2f45534
+    DistributedAppStatus:
+      type: object
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+          description: When true, the component is installed in the connected NetSuite account.
+        URL:
+          type: string
+          description: |-
+            Install link for the component. Absent when `success` is true; the integrator.io UI
+            reads it to render its install prompt when the component is missing.
     SObjectType:
       type: object
       description: |