@celigo/api-specs 0.2.1

package/dist/marketplace.yml

@@ -0,0 +1,685 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Marketplace
+  description: API for browsing Celigo marketplace listings — Integration Apps and templates — and previewing template contents.
+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: Marketplace
+    description: |-
+      Browse Celigo marketplace content. The marketplace contains two types
+      of entries:
+
+      - **Integration Apps** — licensed, Celigo-built connectors (e.g.
+        Shopify–NetSuite) that install with managed updates.
+      - **Templates** — reusable integration blueprints that create a set of
+        resources (integration, connections, flows, exports, imports, scripts)
+        when installed.
+
+      You can preview what a template would create before committing to the
+      install.
+
+      ## Marketplace entry schema
+
+      {% openapi-schemas spec="marketplace" schemas="MarketplaceEntry" grouped="true" %}
+paths:
+  /v1/templates/{_id}/preview:
+    get:
+      x-internal: false
+      operationId: previewTemplate
+      tags:
+        - Marketplace
+      summary: Preview a template's installed resource docs
+      description: |-
+        Returns the concrete resource documents a template would create if
+        installed. The response is an envelope `{objects, stackRequired}` where
+        `objects` is an array of `{model, doc}` entries — one per resource that
+        the install step would materialize.
+
+        `stackRequired` is `true` when the template includes NetSuite-distributed
+        resources that need a dedicated stack — the installer prompts for one
+        before the install proceeds.
+
+        The ID must belong to a Template, not a Connector (Integration App).
+        Connector IDs from `/v1/published` return 404 here -- pull template
+        IDs from the `Template`-typed entries of `POST /v1/published/combined`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Template id from `POST /v1/published/combined`.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 606e109607404c69e620a938
+      responses:
+        '200':
+          description: Template preview envelope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemplatePreviewResponse'
+              examples:
+                default:
+                  summary: Shopify - NetSuite template preview
+                  value:
+                    stackRequired: false
+                    objects:
+                      - model: Integration
+                        doc:
+                          _id: 6405b9d73496e05ff253d587
+                          name: Shopify - NetSuite
+                          description: Sync Abandoned Checkouts, Collects, … between Shopify and NetSuite.
+                          installSteps:
+                            - name: NetSuite Connection
+                              completed: true
+                              type: connection
+                              sourceConnection:
+                                type: netsuite
+                                name: NetSuite Connection
+                      - model: Connection
+                        doc:
+                          _id: 61f92026dd053843b5d72350
+                          type: netsuite
+                          name: NetSuite Connection
+                          netsuite:
+                            wsdlVersion: '2020.2'
+                            concurrencyLevel: 1
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No template matched the id. Most commonly: the id belongs to a
+            Connector (Integration App) rather than a Template — Connectors are
+            installed via `/v1/integrations/<id>/install`, not through this
+            preview endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidRef:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Template not found.
+  /v1/published:
+    get:
+      x-internal: false
+      operationId: listPublishedConnectors
+      tags:
+        - Marketplace
+      summary: List published Integration Apps (Connectors)
+      description: |-
+        Returns the marketplace catalog of **Integration Apps** — the
+        Celigo-built, fully-managed connectors that install as a single
+        integration. Roughly 30 entries curated by Celigo.
+
+        Each item is a marketplace listing, not an integration instance —
+        `_id` is the marketplace entry id, the `applications` array enumerates
+        the systems the connector bridges, and `numInstalls` is the live install
+        counter across all Celigo accounts.
+
+        For a combined list that also includes user-installable Templates,
+        use `POST /v1/published/combined` instead. Entries here have no
+        `docType` field -- that discriminator only appears in the combined
+        endpoint's response.
+      responses:
+        '200':
+          description: Array of Integration App (Connector) marketplace entries.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MarketplaceEntry'
+              examples:
+                default:
+                  summary: One Integration App entry
+                  value:
+                    - _id: 58c90bccc13f547763bf2fc1
+                      name: Amazon - NetSuite
+                      description: Amazon - NetSuite Integration App helps online retailers combine the powerful Amazon Online Marketplace platform with the proven back-office features of NetSuite.
+                      imageURL: /images/company-logos/amazon-netsuite.png
+                      websiteURL: https://www.celigo.com/products/netsuite-amazon-connector/
+                      applications:
+                        - amazonmws
+                        - netsuite
+                      user:
+                        name: Celigo Etail
+                        company: Celigo
+                      trialEnabled: false
+                      lastModified: '2026-04-22T14:23:56.528Z'
+                      numInstalls: 1938
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/published/combined:
+    post:
+      x-internal: false
+      operationId: listPublishedCombined
+      tags:
+        - Marketplace
+      summary: List Integration Apps and Templates together
+      description: |-
+        Returns a unified array of **all** marketplace content — both Integration
+        Apps (`docType: Connector`) and Templates (`docType: Template`). Each
+        entry carries the `docType` discriminator so callers can partition.
+
+        Despite being a POST, this is a **read-only, safe** endpoint — the body
+        is an empty `{}` in the default CLI invocation. POST is used purely to
+        carry sort and filter parameters that don't fit cleanly in a query
+        string. The route is POST-only.
+
+        Always send `Content-Type: application/json` with at least `{}` as
+        the body. For Connector-only listings, `GET /v1/published` is
+        lighter.
+      parameters:
+        - name: sort_by
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - numInstalls
+              - name
+              - lastModified
+            x-enumDescriptions:
+              numInstalls: Sort by number of installs (descending).
+              name: Sort alphabetically by name.
+              lastModified: Sort by last modification date.
+          description: |-
+            Sort key. `numInstalls` (descending) matches the CLI default.
+            Omitting `sort_by` returns results in server-default order.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |-
+                Body is required (even if empty) because the endpoint is POST
+                and the server enforces `Content-Type: application/json` —
+                otherwise 415. No fields inside the body are currently honored by
+                the server for filtering.
+            examples:
+              empty:
+                summary: Default — all content
+                value: {}
+      responses:
+        '200':
+          description: Array of marketplace entries, both Connectors and Templates.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MarketplaceEntry'
+              examples:
+                mixed:
+                  summary: One Connector + one Template, sorted by numInstalls
+                  value:
+                    - _id: 54fa0b38a7044f9252000036
+                      name: Shopify - NetSuite
+                      docType: Connector
+                      description: Sync products, orders, fulfillments, and inventory between Shopify and NetSuite.
+                      applications:
+                        - netsuite
+                        - 65bb6a09de4fef278556c5fe
+                      user:
+                        name: Celigo Etail
+                        company: Celigo
+                      trialEnabled: false
+                      lastModified: '2026-04-22T07:14:42.124Z'
+                      numInstalls: 3672
+                    - _id: 606e109607404c69e620a938
+                      name: Error automation via integrator.io APIs
+                      docType: Template
+                      description: Template that automates flow error handling via integrator.io APIs.
+                      applications:
+                        - integrator.io
+                      user:
+                        name: Celigo
+                        company: Celigo
+                      lastModified: '2024-06-17T19:32:04.000Z'
+                      numInstalls: 12
+        '400':
+          description: |-
+            Typically `invalid_query_param` when `sort_by` is outside the
+            accepted enum.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidSortBy:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter "sort_by" has invalid value.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '415':
+          description: |-
+            Request lacked `Content-Type: application/json`. The server refuses
+            to accept the body and returns this even when the body is an empty
+            string.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noContentType:
+                  value:
+                    errors:
+                      - code: unsupported_media_type
+                        message: Content-Type should equal application/json
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    TemplatePreviewResponse:
+      type: object
+      description: |-
+        Envelope describing what a template's install would produce. `objects[]`
+        enumerates each resource doc the installer would create, tagged by
+        `model`. The docs are populated with the template's defaults and
+        placeholder ids that the installer rewrites during the real install.
+      properties:
+        objects:
+          type: array
+          description: |-
+            Resource docs the installer would materialize. Ordering is
+            typically `Integration` first (exactly one), then `Connection`s,
+            `Export`s, `Import`s, `Flow`s, `Script`s.
+          items:
+            type: object
+            description: One resource doc tagged with its model type.
+            properties:
+              model:
+                type: string
+                enum:
+                  - Integration
+                  - Connection
+                  - Export
+                  - Import
+                  - Flow
+                  - Script
+                  - AsyncHelper
+                x-enumDescriptions:
+                  Integration: Integration workspace resource.
+                  Connection: Connection resource for authenticating to external systems.
+                  Export: Export resource for reading data from a source system.
+                  Import: Import resource for writing data to a destination system.
+                  Flow: Flow resource for data integration pipelines.
+                  Script: Script resource for custom JavaScript hooks.
+                  AsyncHelper: Async helper resource for polling-based connection patterns.
+                description: Resource class this doc describes.
+              doc:
+                type: object
+                description: |-
+                  The concrete resource document. Shape matches the write shape
+                  of the corresponding resource endpoint (e.g. `POST /v1/flows`,
+                  `POST /v1/exports`, etc.). Fields are populated with the
+                  template's defaults; ids are placeholders that the installer
+                  replaces during the real install.
+                additionalProperties: true
+        stackRequired:
+          type: boolean
+          description: |-
+            `true` when the template includes NetSuite-distributed resources
+            that need a dedicated stack — the installer prompts for one before
+            the install proceeds. `false` for Shopify / HTTP / file-only
+            templates.
+    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
+    MarketplaceEntry:
+      type: object
+      required:
+        - _id
+        - name
+        - description
+        - applications
+        - numInstalls
+        - user
+        - lastModified
+      description: |-
+        A single marketplace listing — either an Integration App (`docType: Connector`)
+        or a Template (`docType: Template`). `docType` is only present in
+        `POST /v1/published/combined` responses; `GET /v1/published` entries (Connectors
+        only) omit the field.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Marketplace entry id. For Templates, use this with `/v1/templates/{_id}/preview`.
+          examples:
+            - 54fa0b38a7044f9252000036
+        name:
+          type: string
+          description: Display name of the marketplace entry.
+          examples:
+            - Shopify - NetSuite
+        description:
+          type: string
+          description: Marketing description shown in the marketplace listing.
+          examples:
+            - Sync products, orders, fulfillments, and inventory between Shopify and NetSuite.
+        imageURL:
+          type: string
+          description: |-
+            Relative image path (e.g. `/images/company-logos/amazon-netsuite.png`)
+            or absolute URL. Not always present on Template entries.
+          examples:
+            - /images/company-logos/amazon-netsuite.png
+        websiteURL:
+          type: string
+          format: uri
+          description: External product page URL. Rare on Template entries.
+          examples:
+            - https://www.celigo.com/products/netsuite-amazon-connector/
+        applications:
+          type: array
+          description: |-
+            Systems this marketplace entry bridges. Values are either
+            well-known application slugs (`netsuite`, `shopify`, `amazonmws`) or
+            object ids referencing an Application definition.
+          items:
+            type: string
+            examples:
+              - netsuite
+        user:
+          type: object
+          description: Publisher metadata.
+          properties:
+            name:
+              type: string
+              description: Publisher display name.
+              examples:
+                - Celigo Etail
+            company:
+              type: string
+              description: Publisher's company. For Celigo-built content this is `"Celigo"`.
+              examples:
+                - Celigo
+        trialEnabled:
+          type: boolean
+          description: |-
+            Whether this entry offers a trial install. Populated on Integration
+            App entries; rarely set on Templates.
+        lastModified:
+          type: string
+          format: date-time
+          description: When the marketplace entry was last updated.
+          examples:
+            - '2026-04-22T07:14:42.124Z'
+        numInstalls:
+          type: integer
+          description: |-
+            Live install counter across all Celigo accounts. Used as the
+            `sort_by=numInstalls` key.
+          examples:
+            - 3672
+        docType:
+          type: string
+          enum:
+            - Connector
+            - Template
+          x-enumDescriptions:
+            Connector: An Integration App (pre-built integration) available in the marketplace.
+            Template: A reusable integration template that can be installed and customized.
+          description: |-
+            Discriminator distinguishing Integration Apps from Templates. Only
+            populated in `POST /v1/published/combined` responses. Absent in
+            `GET /v1/published` (Connectors only).
+        framework:
+          type: string
+          enum:
+            - twoDotZero
+          x-enumDescriptions:
+            twoDotZero: Integration App uses the 2.0 edition-based framework.
+          description: |-
+            Integration App framework version. Present only on Connector entries
+            that use the 2.0 edition-based architecture. When set, the
+            `twoDotZero` object contains edition metadata.
+        twoDotZero:
+          type: object
+          description: |-
+            Edition metadata for Integration Apps using the 2.0 framework.
+            Present only when `framework` is `twoDotZero`.
+          properties:
+            _integrationId:
+              type: string
+              format: objectId
+              description: Integration id that backs this Integration App.
+              x-celigo-refModel: integrations
+              examples:
+                - 6405b9d73496e05ff253d587
+            editions:
+              type: array
+              description: Available editions (e.g. Starter, Professional). Empty when no editions are configured.
+              items:
+                type: object
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    description: System-generated unique identifier for the edition.
+                    examples:
+                      - 66a1f2c3b4d5e6f7a8b9c0d1
+                  displayName:
+                    type: string
+                    description: Edition label shown to users (e.g. "Starter Edition").
+                    examples:
+                      - Starter Edition
+                  order:
+                    type: integer
+                    description: Display order among editions.
+                    examples:
+                      - 1
+                  resources:
+                    type: object
+                    description: Resource ids included in this edition.
+                    properties:
+                      _flowIds:
+                        type: array
+                        description: Ids of the flows included in this edition.
+                        x-celigo-refModel: flows
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 66b2c3d4e5f6a7b8c9d0e1f2
+                      _importIds:
+                        type: array
+                        description: Ids of the imports included in this edition.
+                        x-celigo-refModel: imports
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 66c3d4e5f6a7b8c9d0e1f2a3
+                      _exportIds:
+                        type: array
+                        description: Ids of the exports included in this edition.
+                        x-celigo-refModel: exports
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 66d4e5f6a7b8c9d0e1f2a3b4
+                      _connectionIds:
+                        type: array
+                        description: Ids of the connections included in this edition.
+                        x-celigo-refModel: connections
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 66e5f6a7b8c9d0e1f2a3b4c5
+                      _asyncHelperIds:
+                        type: array
+                        description: Ids of the async helpers included in this edition.
+                        x-celigo-refModel: asynchelpers
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 66f6a7b8c9d0e1f2a3b4c5d6
+                      _fileDefinitionIds:
+                        type: array
+                        description: Ids of the file definitions included in this edition.
+                        x-celigo-refModel: filedefinitions
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 6607a8b9c0d1e2f3a4b5c6d7
+                  childResources:
+                    type: object
+                    description: Child resource ids (for parent-child Integration Apps).
+                    properties:
+                      _flowIds:
+                        type: array
+                        description: Ids of the flows included in this edition's child integrations.
+                        x-celigo-refModel: flows
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 6618b9c0d1e2f3a4b5c6d7e8
+                      _importIds:
+                        type: array
+                        description: Ids of the imports included in this edition's child integrations.
+                        x-celigo-refModel: imports
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 6629c0d1e2f3a4b5c6d7e8f9
+                      _exportIds:
+                        type: array
+                        description: Ids of the exports included in this edition's child integrations.
+                        x-celigo-refModel: exports
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 663ad1e2f3a4b5c6d7e8f9a0
+                      _connectionIds:
+                        type: array
+                        description: Ids of the connections included in this edition's child integrations.
+                        x-celigo-refModel: connections
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 664be2f3a4b5c6d7e8f9a0b1
+                      _asyncHelperIds:
+                        type: array
+                        description: Ids of the async helpers included in this edition's child integrations.
+                        x-celigo-refModel: asynchelpers
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 665cf3a4b5c6d7e8f9a0b1c2
+                      _fileDefinitionIds:
+                        type: array
+                        description: Ids of the file definitions included in this edition's child integrations.
+                        x-celigo-refModel: filedefinitions
+                        items:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 666da4b5c6d7e8f9a0b1c2d3
+            isParentChild:
+              type: boolean
+              description: When true, this Integration App uses the parent-child model.
+  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