@celigo/api-specs 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Celigo, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# Celigo API specs
+
+OpenAPI 3.2 specifications for the [Celigo integrator.io](https://www.celigo.com) REST API. These
+are the source of truth behind the
+[API reference on the Celigo Developer Platform](https://developer.celigo.com/api/api-reference),
+and what the [Celigo CLI](https://developer.celigo.com/cli) validates resource documents against.
+
+Every platform resource gets its own OpenAPI document — 44 published specs covering connections,
+flows, exports, imports, integrations, jobs, scripts, tools, and the rest.
+
+## The API these specs describe
+
+All operations live under the `/v1/` prefix and authenticate with a bearer token
+(`Authorization: Bearer <token>`). Create a token in integrator.io under **Resources** >
+**API tokens**.
+
+The API is served from four regional hosts. Use the one your account lives in:
+
+| Region       | Base URL                       |
+| ------------ | ------------------------------ |
+| US (default) | `https://api.integrator.io`    |
+| EU           | `https://api.eu.integrator.io` |
+| AU           | `https://api.au.integrator.io` |
+| CA           | `https://api.ca.integrator.io` |
+
+## Getting the specs
+
+To browse the API, read the rendered reference at
+[developer.celigo.com/api/api-reference](https://developer.celigo.com/api/api-reference). Each
+resource has its own page, with a console for trying calls against your own account.
+
+To consume the specs as files — client generation, request validation, or grounding an AI agent on
+the API surface — install the published bundles:
+
+```bash
+npm install @celigo/api-specs
+```
+
+Jenkins publishes the package with `schemas.json` at the package root for `celigo lint` and the
+bundled OpenAPI documents under `dist/` for other consumers. The tarball excludes the authored
+`specs/` tree, tests, scripts, internal operations, deprecated fields, and source-only metadata.
+
+Each resource ships as one self-contained OpenAPI 3.2 document with every `$ref` already inlined,
+so a spec file can go straight to a generator or validator with no loader configuration.
+
+## What the specs cover
+
+The specs are prescriptive. They describe the API surface Celigo supports and intends to keep
+supporting — not everything the server happens to tolerate. Internal endpoints, deprecated fields,
+and retired enum values are deliberately left out of the published documents.
+
+The practical consequence: a request that validates against these specs is one you can build on.
+The reverse does not hold. The live server is frequently more permissive than the spec, and a
+payload it accepts today may be ignored or rejected later if no spec ever described it.
+
+Alongside standard OpenAPI, the specs carry `x-` extensions that Celigo tooling reads —
+`x-enumDescriptions` explains what each enum value does, `x-celigo-refModel` names the resource an
+ID field points at, and a handful of others. Standard OpenAPI consumers can ignore them;
+[CONTRIBUTING.md](CONTRIBUTING.md) documents what each one means.
+
+## Repository layout
+
+Specs are authored as multi-file `$ref` trees and bundled into the single-file documents that get
+published.
+
+```
+specs/v1/               authored source, one directory per resource
+  common/                 schemas and responses shared across specs
+  connection/
+    connection.yml        spec root: info, servers, security, path refs
+    paths/*.yml           path item objects
+    components/schemas/   request and response schemas
+  flow/
+  ...
+redocly.yaml            spec registry, lint rules, and publish decorators
+scripts/                bundling, validation gates, and publishing
+tests/live/             contract tests that exercise the specs against the live API
+```
+
+`specs/v1/` mirrors the `/v1/` URL prefix. A future breaking version would land in a sibling
+`specs/v2/` tree; additive v2 endpoints go straight into the existing spec files.
+
+## Development
+
+```bash
+npm ci
+npm run lint      # Redocly lint across every registered spec
+npm run bundle    # validation gates, then bundle to dist/
+```
+
+Needs Node.js 20 or newer, plus Python 3 with PyYAML for the validation gates. `dist/` is
+generated output — never hand-edit it.
+
+[CONTRIBUTING.md](CONTRIBUTING.md) carries the authoring rules: description style, schema
+patterns, the `x-` extension contracts, how to register a new spec, and how publishing works.
+[tests/live/README.md](tests/live/README.md) covers the contract test suite.
+
+## Support
+
+Contact [Celigo Support](https://docs.celigo.com/hc/en-us/requests/new) for a problem with the
+specs — a schema that disagrees with the API, a missing field or endpoint, a description that led
+you somewhere wrong — and for integrator.io behavior, account access, or a production incident.
+If you can reach this repository, an issue works too.
+
+Report a suspected vulnerability privately, never in a public issue: use GitHub's **Report a
+vulnerability** option if you can reach this repository, otherwise
+[Celigo Support](https://docs.celigo.com/hc/en-us/requests/new). Never include tokens,
+credentials, or customer data.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The specs describe the integrator.io API; use of the API itself is
+governed by your Celigo agreement.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the authoring rules and how publishing works.
+Participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md); [SECURITY.md](SECURITY.md) and
+[SUPPORT.md](SUPPORT.md) carry the full policies.