@celigo/api-specs 0.2.27 → 0.2.28

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "b5d5c35",
+		"iasCommit": "dd3c0db",
 		"generatedAt": "2026-09-18"
 	},
 	"roots": {