@celigo/api-specs 0.2.10 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +70 -81
  2. package/dist/export.yml +193 -613
  3. package/dist/tool.yml +193 -613
  4. package/package.json +13 -1
  5. package/schemas.json +493 -436
package/README.md CHANGED
@@ -1,12 +1,47 @@
1
- # Celigo API specs
1
+ <!--
2
+ This file ships as the README of the @celigo/api-specs npm package. Its audience is public, so it
3
+ must not describe repository internals or link into the repository. The repository README is
4
+ .github/README.md, which GitHub renders in place of this one.
5
+ -->
2
6
 
3
- OpenAPI 3.2 specifications for the [Celigo integrator.io](https://www.celigo.com) REST API. These
4
- are the source of truth behind the
7
+ # @celigo/api-specs
8
+
9
+ OpenAPI 3.2 specifications for the [Celigo integrator.io](https://www.celigo.com) REST API,
10
+ packaged as files for tooling. They are the documents behind the
5
11
  [API reference on the Celigo Developer Platform](https://developer.celigo.com/api/api-reference),
6
12
  and what the [Celigo CLI](https://developer.celigo.com/cli) validates resource documents against.
7
13
 
8
- Every platform resource gets its own OpenAPI document — 44 published specs covering connections,
9
- flows, exports, imports, integrations, jobs, scripts, tools, and the rest.
14
+ ```bash
15
+ npm install @celigo/api-specs
16
+ ```
17
+
18
+ ## What's in the package
19
+
20
+ Every platform resource has its own OpenAPI document under `dist/` — connections, flows, exports,
21
+ imports, integrations, jobs, scripts, tools, and the rest. Each file is self-contained, with every
22
+ `$ref` already inlined, so it can go straight into a client generator, a request validator, or an
23
+ AI agent's context with no loader configuration.
24
+
25
+ ```
26
+ dist/connection.yml
27
+ dist/flow.yml
28
+ dist/export.yml
29
+ dist/import.yml
30
+ ...
31
+ schemas.json
32
+ ```
33
+
34
+ `schemas.json` is the schema pack that the Celigo CLI's `celigo lint` command validates documents
35
+ against, compiled from the same bundles. Other consumers can ignore it.
36
+
37
+ Resolve a document the same way as any other packaged file:
38
+
39
+ ```js
40
+ import { createRequire } from "node:module";
41
+
42
+ const require = createRequire(import.meta.url);
43
+ const specPath = require.resolve("@celigo/api-specs/dist/connection.yml");
44
+ ```
10
45
 
11
46
  ## The API these specs describe
12
47
 
@@ -23,97 +58,51 @@ The API is served from four regional hosts. Use the one your account lives in:
23
58
  | AU | `https://api.au.integrator.io` |
24
59
  | CA | `https://api.ca.integrator.io` |
25
60
 
26
- ## Getting the specs
27
-
28
- To browse the API, read the rendered reference at
29
- [developer.celigo.com/api/api-reference](https://developer.celigo.com/api/api-reference). Each
30
- resource has its own page, with a console for trying calls against your own account.
31
-
32
- To consume the specs as files — client generation, request validation, or grounding an AI agent on
33
- the API surface — install the published bundles:
34
-
35
- ```bash
36
- npm install @celigo/api-specs
37
- ```
38
-
39
- Jenkins publishes the package with `schemas.json` at the package root for `celigo lint` and the
40
- bundled OpenAPI documents under `dist/` for other consumers. The tarball excludes the authored
41
- `specs/` tree, tests, scripts, internal operations, deprecated fields, and source-only metadata.
42
-
43
- Each resource ships as one self-contained OpenAPI 3.2 document with every `$ref` already inlined,
44
- so a spec file can go straight to a generator or validator with no loader configuration.
61
+ To browse the API interactively, use the
62
+ [rendered reference](https://developer.celigo.com/api/api-reference): each resource has its own
63
+ page, with a console for trying calls against your own account.
45
64
 
46
65
  ## What the specs cover
47
66
 
48
67
  The specs are prescriptive. They describe the API surface Celigo supports and intends to keep
49
68
  supporting — not everything the server happens to tolerate. Internal endpoints, deprecated fields,
50
- and retired enum values are deliberately left out of the published documents.
69
+ and retired enum values are deliberately left out.
51
70
 
52
71
  The practical consequence: a request that validates against these specs is one you can build on.
53
- The reverse does not hold. The live server is frequently more permissive than the spec, and a
54
- payload it accepts today may be ignored or rejected later if no spec ever described it.
55
-
56
- Alongside standard OpenAPI, the specs carry `x-` extensions that Celigo tooling reads —
57
- `x-enumDescriptions` explains what each enum value does, `x-celigo-refModel` names the resource an
58
- ID field points at, and a handful of others. Standard OpenAPI consumers can ignore them;
59
- [CONTRIBUTING.md](CONTRIBUTING.md) documents what each one means.
60
-
61
- ## Repository layout
62
-
63
- Specs are authored as multi-file `$ref` trees and bundled into the single-file documents that get
64
- published.
72
+ The reverse does not hold. The server may accept a payload no spec describes, and that payload may
73
+ be ignored or rejected later.
65
74
 
66
- ```
67
- specs/v1/ authored source, one directory per resource
68
- common/ schemas and responses shared across specs
69
- connection/
70
- connection.yml spec root: info, servers, security, path refs
71
- paths/*.yml path item objects
72
- components/schemas/ request and response schemas
73
- flow/
74
- ...
75
- redocly.yaml spec registry, lint rules, and publish decorators
76
- scripts/ bundling, validation gates, and publishing
77
- tests/live/ contract tests that exercise the specs against the live API
78
- ```
79
-
80
- `specs/v1/` mirrors the `/v1/` URL prefix. A future breaking version would land in a sibling
81
- `specs/v2/` tree; additive v2 endpoints go straight into the existing spec files.
82
-
83
- ## Development
75
+ ## Extensions
84
76
 
85
- ```bash
86
- npm ci
87
- npm run lint # Redocly lint across every registered spec
88
- npm run bundle # validation gates, then bundle to dist/
89
- ```
77
+ Alongside standard OpenAPI, the documents carry `x-` extensions that Celigo tooling reads. Standard
78
+ OpenAPI consumers can ignore them; validators and AI agents may find them useful.
90
79
 
91
- Needs Node.js 20 or newer, plus Python 3 with PyYAML for the validation gates. `dist/` is
92
- generated output — never hand-edit it.
80
+ | Extension | Where | Meaning |
81
+ | ------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82
+ | `x-enumDescriptions` | Fields with `enum` | One line per enum value explaining what it does. |
83
+ | `x-celigo-refModel` | ID fields | The resource type the ID points at (`flows`, `scripts`, and so on). |
84
+ | `x-celigo-ai-guidance` | Schemas and fields | Operational hints for AI agents: which default to choose, what to set when scaffolding, and the concrete failure that results from getting it wrong. |
85
+ | `x-celigo-ui-override` | Schemas and fields | Marks a requirement or default that mirrors the integrator.io form, which is stricter than the raw API, so generated configurations are complete and connectable. |
86
+ | `x-celigo-agent` | Expression fields | How the field is authored — capability tags such as `handlebars`, `sql`, `graphql`, `filter`, `mapping`, `script`. |
87
+ | `x-celigo-handlebars-context` | Handlebars fields | The data context the expression is evaluated against, such as `pre-mapped` or `post-mapped`. |
88
+ | `x-celigo-excludeAdaptorTypes` | Shared adaptor fields | Adaptor types the field does not apply to. |
89
+ | `x-lowercase`, `x-uppercase` | String fields | The API normalizes the value's case on save. |
93
90
 
94
- [CONTRIBUTING.md](CONTRIBUTING.md) carries the authoring rules: description style, schema
95
- patterns, the `x-` extension contracts, how to register a new spec, and how publishing works.
96
- [tests/live/README.md](tests/live/README.md) covers the contract test suite.
91
+ `x-internal`, `x-enable-proxy`, and `x-displayName` control the documentation toolchain and carry no
92
+ API meaning.
97
93
 
98
94
  ## Support
99
95
 
100
- Contact [Celigo Support](https://docs.celigo.com/hc/en-us/requests/new) for a problem with the
101
- specs — a schema that disagrees with the API, a missing field or endpoint, a description that led
102
- you somewhere wrong — and for integrator.io behavior, account access, or a production incident.
103
- If you can reach this repository, an issue works too.
96
+ For a problem with the specs — a schema that disagrees with the API, a missing field or endpoint, a
97
+ description that led you somewhere wrong — or with integrator.io itself, contact
98
+ [Celigo Support](https://docs.celigo.com/hc/en-us/requests/new). The most useful report names the
99
+ spec and operation, shows the request you made, and shows what the API returned next to what the
100
+ spec said it would. Never include API tokens, credentials, or customer data.
104
101
 
105
- Report a suspected vulnerability privately, never in a public issue: use GitHub's **Report a
106
- vulnerability** option if you can reach this repository, otherwise
107
- [Celigo Support](https://docs.celigo.com/hc/en-us/requests/new). Never include tokens,
108
- credentials, or customer data.
102
+ Report a suspected security vulnerability through the same channel, privately, with the spec and
103
+ operation involved, what it discloses or enables, and reproduction steps.
109
104
 
110
105
  ## License
111
106
 
112
- MIT — see [LICENSE](LICENSE). The specs describe the integrator.io API; use of the API itself is
113
- governed by your Celigo agreement.
114
-
115
- ## Contributing
116
-
117
- [CONTRIBUTING.md](CONTRIBUTING.md) has the authoring rules and how publishing works.
118
- Participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md); [SECURITY.md](SECURITY.md) and
119
- [SUPPORT.md](SUPPORT.md) carry the full policies.
107
+ MIT. The `LICENSE` file ships in the package. The specs describe the integrator.io API; use of the
108
+ API itself is governed by your Celigo agreement.