@wildo-ai/external-connectors-models 1.1.11 → 1.1.13

package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts

@@ -0,0 +1,254 @@
+/**
+ * GRAPHQL provider operations (#3392): an operation whose provider-owned part is a GraphQL document, and whose input is
+ * the document's VARIABLES.
+ *
+ * A REST operation is a method, a path and a body built from the caller's input. A GraphQL vendor (GitHub v4, Linear,
+ * Shopify Admin, monday.com) exposes ONE endpoint and tells operations apart by the query document sent to it. Written
+ * as a REST operation, the document had to be an input, which handed the caller the vendor's whole schema and made every
+ * operation the same operation. Here the PROVIDER owns the document (`graphql.document`, with its `operationName`), and
+ * the caller supplies only values for the variables that document declares.
+ *
+ * ## The wire, settled by the GraphQL-over-HTTP specification
+ *
+ * The request is a POST whose JSON body holds `query` (the document), `operationName` and `variables`. The client
+ * accepts `application/graphql-response+json` first and `application/json` after it, because the vendor's support for
+ * the newer media type is unknown.
+ * spec-cite: GraphQL over HTTP, Current Working Draft (https://graphql.github.io/graphql-over-http/draft/, fetched
+ * 2026-11-09) — §4.1 lists the request parameters `query` (required), `operationName`, `variables` and `extensions`;
+ * §4.4 "A server MUST support POST requests with a body encoded as UTF-8 JSON, using the `application/json` media type";
+ * §4.2 "the client SHOULD set the Accept header to application/graphql-response+json, application/json;q=0.9".
+ *
+ * ## The answer: errors arrive IN BAND, on a 2xx
+ *
+ * A GraphQL server reports most failures inside a successful HTTP answer, in an `errors` list beside (or instead of)
+ * `data`. Read as REST, such an answer is a success, so a refused call would be returned to its caller as a result. The
+ * rule here, which {@link readProviderGraphqlResponse} applies and the engine's transport enforces on every GraphQL call:
+ *
+ * | the answer | verdict |
+ * |---|---|
+ * | `data` is an object, no `errors` (or an empty list) | SUCCEEDED; the output is read from `data` |
+ * | `errors`, and no `data` entry | REQUEST_ERROR: the server refused before executing anything |
+ * | `errors`, and a `data` entry (null or partial) | EXECUTION_ERROR: execution began and a field failed |
+ * | neither a `data` object nor `errors` | UNSTATED: the answer does not say what happened |
+ * | `data`, no `errors`, and the mutation's declared `payloadRefusal` says refused | PAYLOAD_REFUSED: the vendor did not do the write |
+ *
+ * spec-cite: GraphQL, September 2025 edition (https://spec.graphql.org/September2025/, fetched 2026-11-09) — §7.1.1
+ * "If execution raised any errors, the execution result must contain an entry with key "errors"" and "The value of this
+ * entry must be a non-empty list"; §7.1.3 "The request error result map must not contain an entry with key "data""; §7.1.5
+ * "If an error was raised during the execution that prevented a valid response, the "data" entry in the response should
+ * be null"; §6.3.4 (mutation) "the selections in the top most selection set will be executed in serial order".
+ * spec-cite: https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api — for the
+ * primary rate limit "the response status will still be `200`", fetched 2026-11-09: a 200 is not a success.
+ *
+ * PARTIAL DATA IS NEVER RETURNED AS A RESULT. Any error fails the call, whatever `data` holds, because a caller handed a
+ * partial object cannot tell a field the vendor left null from a field that failed. For a MUTATION whose execution began,
+ * the failure says the outcome is UNKNOWN: the root fields run in order and an error in one does not undo the ones
+ * before it, so whether the change landed is not stated. A request error (no `data`) applied nothing, mutation or not.
+ *
+ * ## What is not checked here
+ *
+ * The document is checked for its SHAPE (it parses into exactly one operation of the declared name and type, and its
+ * variables are the input's fields). It is not validated against the vendor's schema here: publish does that, against
+ * the schema the module pins as `provider.graphqlSchema` (#3392, the counterpart of the OpenAPI conformance check of
+ * #2028). The OpenAPI conformance check skips a GraphQL operation, since an OpenAPI description does not describe a
+ * GraphQL endpoint.
+ */
+import { type ProviderRestOperation } from './rest-operations.external-connectors-models.schemas';
+/** @wildo_source:part:start external-connectors.models.rest-operation-contract facet:layer:shared facet:family:provider facet:audience:app-developer */
+/**
+ * The GraphQL document a provider operation sends (#3392), set as `ProviderRestOperation.graphql`.
+ *
+ * With it the operation is a GraphQL call: `method` must be `POST`, `pathTemplate` is the vendor's GraphQL endpoint
+ * (`/graphql`), and the operation's input IS the variables. So it may declare no `requestBody`, and no parameter fed by
+ * the input (a `constantValue` header or path parameter, such as a pinned API version, is allowed). `inputSchema`
+ * describes the variables, one top-level field per variable the document declares, and `inputOptions` work on them as on
+ * any input. `resultPath` and `outputSchema` read the answer's `data`, never the `{ data, errors }` envelope around it.
+ * `responseDecoding` stays JSON.
+ *
+ * Checked when the catalogue loads, at publish and on every call ({@link describeProviderRestOperationGraphqlDefects}).
+ *
+ * @example
+ * // GitHub: a repository's discussions, which GitHub serves through GraphQL only.
+ * {
+ *   operationId: 'github_issues_list_discussions', domain: 'default', method: API_HttpMethod.POST, pathTemplate: '/graphql',
+ *   classification: ExternalOperation_Classification.READ,
+ *   graphql: {
+ *     operationName: 'ListDiscussions',
+ *     document: 'query ListDiscussions($owner: String!, $repo: String!, $first: Int!) { repository(owner: $owner, name: $repo) { discussions(first: $first) { nodes { number title } } } }',
+ *   },
+ *   inputSchema: z.strictObject({ owner: z.string(), repo: z.string(), first: z.number().int() }),
+ *   resultPath: 'repository.discussions',
+ * }
+ */
+export interface ProviderRestOperationGraphql {
+    /**
+     * The executable document, owned by the provider: exactly ONE operation (a `query` or a `mutation`, named
+     * {@link operationName}) and any fragments it uses. A `query` is a READ operation and a `mutation` a WRITE; a
+     * `subscription` is refused, since it is not answered over a single POST.
+     */
+    readonly document: string;
+    /** The operation's name in {@link document}, sent as `operationName`. */
+    readonly operationName: string;
+    /**
+     * Dot path, inside EACH error of the answer's `errors` list, to the vendor's machine-readable code (`extensions.code`
+     * by convention, where a vendor uses it). The specification standardizes no code, so absent, no code is read and the
+     * failure carries the vendor's messages only. A code is kept only when it is code-shaped, as every vendor code is.
+     */
+    readonly errorCodePath?: string;
+    /**
+     * The codes, read at {@link errorCodePath}, that mean the vendor refused the CREDENTIAL itself rather than the request
+     * (#3392): the stored credential is then recorded as rejected, as a REST vendor's
+     * `applicationOutcome.credentialRefusedErrorCodes` records it. A GraphQL vendor may name a dead or expired token inside
+     * a 200 (an error list beside or instead of `data`) or inside a 4xx carrying the same error list, and both are read.
+     * The failure itself is unchanged: the call fails with the vendor's code and is never retried.
+     *
+     * List only a code the vendor DOCUMENTS as a refused credential. A code for a resource the credential may not reach
+     * (`FORBIDDEN` on one repository), for a missing scope, or for a request sent with no credential at all, does not
+     * belong here: the credential still works, and recording it rejected would show a working connection as broken.
+     * Requires {@link errorCodePath}, without which no code is read and none could match.
+     *
+     * @example
+     * // monday.com answers a key it refuses with the error code `Unauthorized`, whose documented resolution is a valid key.
+     * // spec-cite: https://developer.monday.com/api-reference/docs/errors — the `Unauthorized` row (HTTP 401, resolution
+     * // "Input a valid API key."), fetched 2026-11-09.
+     * graphql: { operationName: 'CreateItem', document: CREATE_ITEM, errorCodePath: 'extensions.code', credentialRefusedErrorCodes: ['Unauthorized'] }
+     */
+    readonly credentialRefusedErrorCodes?: readonly string[];
+    /**
+     * Where a MUTATION's answer says the vendor refused it in the DATA rather than in `errors` (follow-up to #3392). Several
+     * GraphQL vendors answer a write they refused with a successful response whose payload carries the refusal: Shopify's
+     * `userErrors` list ("validation failures, such as invalid field values or business logic violations, that prevent the
+     * operation from completing"), Linear's `success: Boolean!`. Without it such an answer is returned as the result and a
+     * caller that does not read the payload takes a refused write for a done one; with it the call FAILS, carrying the
+     * vendor's messages, exactly as an `errors` entry does. See {@link ProviderGraphqlPayloadRefusal}.
+     * spec-cite: https://shopify.dev/docs/api/admin-graphql — the `UserError` description quoted above, fetched 2026-11-10.
+     *
+     * @example
+     * // Shopify: productCreate's userErrors, each `{ field, message }`.
+     * payloadRefusal: { kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS, path: 'productCreate.userErrors', messagePath: 'message', fieldPath: 'field' }
+     */
+    readonly payloadRefusal?: ProviderGraphqlPayloadRefusal;
+}
+/** How a mutation's payload states a refusal. See {@link ProviderRestOperationGraphql.payloadRefusal}. */
+export declare enum ProviderGraphqlPayloadRefusalKind {
+    /** A list of the vendor's refusals (Shopify's `userErrors`): the write was refused when the list is not empty. */
+    USER_ERRORS = "user_errors",
+    /** A boolean the vendor sets to `false` when it did not do the write (Linear's `success`). */
+    SUCCESS_FLAG = "success_flag"
+}
+/**
+ * Where a mutation's payload states a refusal (follow-up to #3392). Every path is a dot path, `path` from the answer's
+ * `data` (as `resultPath` is), `messagePath`, `fieldPath` and `codePath` from inside each listed refusal.
+ *
+ * - {@link ProviderGraphqlPayloadRefusalKind.USER_ERRORS}: a non-empty list at `path` fails the call. Each entry's text at
+ *   `messagePath` (`message` when absent) is kept, prefixed with the input field it names at `fieldPath` (a string or a
+ *   list of path segments), and the first code-shaped value at `codePath` is the failure's code.
+ * - {@link ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG}: `false` at `path` fails the call.
+ *
+ * Anything else at `path` (an absent payload, `true`, an empty list) refuses nothing: the answer is read as it is.
+ */
+export type ProviderGraphqlPayloadRefusal = {
+    readonly kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS;
+    readonly path: string;
+    readonly messagePath?: string;
+    readonly fieldPath?: string;
+    readonly codePath?: string;
+} | {
+    readonly kind: ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG;
+    readonly path: string;
+};
+/** What a GraphQL document's operation does. A `subscription` is not served over a single POST, so it is no member. */
+export declare enum ProviderGraphqlOperationType {
+    /** Reads. The operation must be classified READ. */
+    QUERY = "query",
+    /** Changes the vendor. The operation must be classified WRITE. */
+    MUTATION = "mutation"
+}
+/**
+ * The `Accept` a GraphQL call sends: the GraphQL response media type first, `application/json` for a server that predates
+ * it (GraphQL over HTTP §4.2, quoted in this module's header).
+ * semantic-literal-boundary: the media types GraphQL over HTTP names, sent on the wire.
+ */
+export declare const PROVIDER_GRAPHQL_ACCEPT_HEADER = "application/graphql-response+json, application/json;q=0.9";
+/** At most this many of the vendor's error messages are kept on a failure. */
+export declare const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES = 10;
+/** A kept error message is cut at this many characters. */
+export declare const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH = 500;
+/** One operation a document defines, as {@link readProviderGraphqlDocument} reads it. */
+export interface ProviderGraphqlDocumentOperation {
+    /** `query`, `mutation` or `subscription`, as written (an anonymous `{ … }` is a query). */
+    readonly type: string;
+    /** Absent for an anonymous operation. */
+    readonly name?: string;
+    /** The variables it declares, without their `$`, in order. */
+    readonly variables: readonly string[];
+}
+/** What a document holds, or why it cannot be read. */
+export interface ProviderGraphqlDocumentShape {
+    readonly operations: readonly ProviderGraphqlDocumentOperation[];
+    /** Set when the text is not a document of executable definitions. `operations` is then what was read before it. */
+    readonly defect?: string;
+}
+/**
+ * The executable definitions of a GraphQL document (#3392): each operation's type, name and declared variables. A
+ * fragment is skipped; a type-system definition (`type`, `schema`, …) is a defect, since a document sent to a server is
+ * executable only.
+ */
+export declare function readProviderGraphqlDocument(document: string): ProviderGraphqlDocumentShape;
+/**
+ * Why a GraphQL operation cannot be sent as declared, or an empty list (#3392). Empty for an operation without
+ * `graphql`. Checked where a catalogue loads (the operation executor, an augmentation merge), at `wildo registry publish`,
+ * and by the request compiler on every call, so the one rule refuses in every place:
+ *
+ * - the call is a POST with no `requestBody`, every parameter carries a `constantValue` (the input is the variables
+ *   and nothing else), and the answer is read as JSON;
+ * - the document reads as exactly ONE operation, named `operationName`, beside any fragments;
+ * - a `query` is classified READ and a `mutation` WRITE; a `subscription` is refused;
+ * - each declared variable is a top-level field of `inputSchema`, and each top-level field is a declared variable, so no
+ *   value a caller supplies is silently dropped (when `inputSchema` lists its fields; without one, the call refuses a
+ *   value for a variable the document does not declare);
+ * - `errorCodePath` is a dot path;
+ * - each of `credentialRefusedErrorCodes` is code-shaped (a value of any other shape is never kept, so it could never
+ *   match), and the list comes with an `errorCodePath` to read the code at;
+ * - a `payloadRefusal` belongs to a mutation, names a kind of its vocabulary, and reads every path as a dot path.
+ */
+export declare function describeProviderRestOperationGraphqlDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'method' | 'classification' | 'parameters' | 'requestBody' | 'responseDecoding' | 'binaryResponse' | 'inputSchema' | 'graphql'>): string[];
+/** The variables a GraphQL operation's document declares, or `undefined` when the document cannot be read. */
+export declare function providerGraphqlOperationVariables(graphql: ProviderRestOperationGraphql): readonly string[] | undefined;
+/** What a GraphQL answer says about the call. See the table in this module's header. */
+export declare enum ProviderGraphqlResponseOutcomeKind {
+    /** `data` is an object and no error was reported. */
+    SUCCEEDED = "succeeded",
+    /** Errors, and no `data` entry: the request was refused before anything executed. Nothing was applied. */
+    REQUEST_ERROR = "request_error",
+    /** Errors beside a `data` entry (null or partial): execution began and something failed. */
+    EXECUTION_ERROR = "execution_error",
+    /** Neither a `data` object nor an error list: the answer does not state what happened. */
+    UNSTATED = "unstated",
+    /**
+     * `data` and no `errors`, and the mutation's payload states the vendor refused it (its declared `payloadRefusal`): the
+     * write was not done, as the vendor says (follow-up to #3392).
+     */
+    PAYLOAD_REFUSED = "payload_refused"
+}
+/** What {@link readProviderGraphqlResponse} read. */
+export interface ProviderGraphqlResponseVerdict {
+    readonly kind: ProviderGraphqlResponseOutcomeKind;
+    /** On SUCCEEDED, the answer's `data` object: what the operation's `resultPath` and `outputSchema` read. */
+    readonly data?: Readonly<Record<string, unknown>>;
+    /**
+     * The vendor's error messages, in its order, at most {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES}, each cut at
+     * {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH} characters. Vendor prose: it may quote what the call sent, so it
+     * travels to the caller and is never written to a log or an audit row by the engine.
+     */
+    readonly errorMessages?: readonly string[];
+    /** The first code-shaped value at the operation's `errorCodePath` among the errors, when one is declared and found. */
+    readonly errorCode?: string;
+}
+/**
+ * Reads a parsed GraphQL answer (#3392). The ONE reader: the engine's transport, for a 2xx and a non-2xx answer alike,
+ * and every test go through it. See the module header for the rule and its sources.
+ */
+export declare function readProviderGraphqlResponse(body: unknown, errorCodePath?: string, payloadRefusal?: ProviderGraphqlPayloadRefusal): ProviderGraphqlResponseVerdict;
+/** @wildo_source:part:end external-connectors.models.rest-operation-contract */
+//# sourceMappingURL=graphql-operations.external-connectors-models.schemas.d.ts.map

package/dist/esm/protocols/graphql-operations.external-connectors-models.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-operations.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../src/protocols/graphql-operations.external-connectors-models.schemas.ts"],"names":[],"mappings":"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"}