@prismatic-io/spectral 10.17.2 → 10.18.1

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 (52) hide show
  1. package/dist/clients/http/index.d.ts +84 -16
  2. package/dist/clients/http/index.js +85 -17
  3. package/dist/component.d.ts +3 -3
  4. package/dist/component.js +8 -8
  5. package/dist/conditionalLogic/index.js +3 -3
  6. package/dist/errors.d.ts +67 -0
  7. package/dist/errors.js +67 -0
  8. package/dist/generators/cniComponentManifest/cli.js +5 -5
  9. package/dist/generators/cniComponentManifest/index.d.ts +1 -1
  10. package/dist/generators/componentManifest/cli.js +6 -6
  11. package/dist/generators/componentManifest/createActions.d.ts +1 -1
  12. package/dist/generators/componentManifest/createActions.js +4 -4
  13. package/dist/generators/componentManifest/createConnections.d.ts +1 -1
  14. package/dist/generators/componentManifest/createConnections.js +4 -4
  15. package/dist/generators/componentManifest/createDataSources.d.ts +1 -1
  16. package/dist/generators/componentManifest/createDataSources.js +4 -4
  17. package/dist/generators/componentManifest/createStaticFiles.d.ts +1 -1
  18. package/dist/generators/componentManifest/createStaticFiles.js +1 -1
  19. package/dist/generators/componentManifest/createTriggers.d.ts +1 -1
  20. package/dist/generators/componentManifest/createTriggers.js +4 -4
  21. package/dist/generators/componentManifest/helpers.js +1 -1
  22. package/dist/generators/componentManifest/index.d.ts +2 -2
  23. package/dist/generators/componentManifest/index.js +1 -1
  24. package/dist/generators/utils/escapeSpecialCharacters.js +1 -1
  25. package/dist/index.d.ts +543 -53
  26. package/dist/index.js +545 -55
  27. package/dist/integration.d.ts +2 -2
  28. package/dist/integration.js +9 -9
  29. package/dist/serverTypes/asyncContext.d.ts +1 -1
  30. package/dist/serverTypes/context.d.ts +1 -1
  31. package/dist/serverTypes/context.js +2 -2
  32. package/dist/serverTypes/convertComponent.d.ts +2 -2
  33. package/dist/serverTypes/convertComponent.js +2 -2
  34. package/dist/serverTypes/convertIntegration.d.ts +3 -3
  35. package/dist/serverTypes/convertIntegration.js +13 -13
  36. package/dist/serverTypes/index.d.ts +2 -7
  37. package/dist/serverTypes/perform.d.ts +1 -1
  38. package/dist/serverTypes/perform.js +1 -1
  39. package/dist/testing.d.ts +195 -31
  40. package/dist/testing.js +197 -33
  41. package/dist/types/ActionPerformFunction.d.ts +6 -6
  42. package/dist/types/ConfigVars.d.ts +6 -6
  43. package/dist/types/ConnectionDefinition.d.ts +1 -1
  44. package/dist/types/index.d.ts +20 -20
  45. package/dist/types/index.js +20 -20
  46. package/dist/types/typeExportComponent.d.ts +15 -15
  47. package/dist/types/typeExportComponent.js +18 -18
  48. package/dist/types/typeExportIntegration.d.ts +17 -17
  49. package/dist/types/typeExportIntegration.js +17 -17
  50. package/dist/util.d.ts +29 -14
  51. package/dist/util.js +366 -108
  52. package/package.json +26 -28
@@ -1,4 +1,4 @@
1
- import type { AxiosInstance, AxiosResponse, AxiosRequestConfig } from "axios";
1
+ import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
2
2
  import { IAxiosRetryConfig } from "axios-retry";
3
3
  import type { ActionInputParameters } from "../../types/ActionInputParameters";
4
4
  import { inputs } from "./inputs";
@@ -35,33 +35,101 @@ export interface ClientProps {
35
35
  }
36
36
  export declare const toAxiosRetryConfig: ({ retryDelay, retryAllErrors, retryCondition, useExponentialBackoff, ...rest }: RetryConfig) => IAxiosRetryConfig;
37
37
  /**
38
- * Creates a reusable Axios HTTP client. See
39
- * https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client
38
+ * Creates a reusable Axios HTTP client pre-configured with a base URL,
39
+ * headers, timeout, and optional retry logic. This is the recommended
40
+ * way to make HTTP requests from custom component actions.
41
+ *
42
+ * @param props Configuration for the HTTP client.
43
+ * @returns An Axios instance configured with the provided options.
44
+ * @see {@link https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client | Using the Built-in HTTP Client}
45
+ * @example
46
+ * import { createClient } from "@prismatic-io/spectral/dist/clients/http";
47
+ *
48
+ * const client = createClient({
49
+ * baseUrl: "https://api.acme.com/v2",
50
+ * headers: { Authorization: `Bearer ${accessToken}` },
51
+ * responseType: "json",
52
+ * timeout: 30000,
53
+ * debug: false,
54
+ * retryConfig: {
55
+ * retries: 3,
56
+ * retryDelay: 1000,
57
+ * useExponentialBackoff: true,
58
+ * retryAllErrors: false,
59
+ * },
60
+ * });
61
+ *
62
+ * const { data } = await client.get("/items");
40
63
  */
41
64
  export declare const createClient: ({ baseUrl, responseType, headers, timeout, params, debug, retryConfig, }: ClientProps) => HttpClient;
42
65
  /**
43
66
  * A global error handler that examines a thrown error and yields additional
44
- * information if the error was produced by Spectral's HTTP client. See
45
- * https://prismatic.io/docs/custom-connectors/error-handling/
46
- * and
47
- * https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client
67
+ * information if the error was produced by Spectral's HTTP client. If the
68
+ * error is an Axios error, returns a structured object with the response
69
+ * `data`, `status`, and `headers`. Otherwise, returns the error as-is.
70
+ *
71
+ * Commonly used as a component-level `hooks.error` handler.
72
+ *
73
+ * @param error A JavaScript error to handle.
74
+ * @returns An error with data, status and headers if it was an Axios error, or the error otherwise.
75
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
76
+ * @example
77
+ * import { component } from "@prismatic-io/spectral";
78
+ * import { handleErrors } from "@prismatic-io/spectral/dist/clients/http";
48
79
  *
49
- * @param error A JavaScript error to handle
50
- * @returns An error with data, status and headers if it was an Axios error, or the error otherwise
80
+ * export default component({
81
+ * key: "acme",
82
+ * display: { label: "Acme", description: "Acme connector", iconPath: "icon.png" },
83
+ * hooks: { error: handleErrors },
84
+ * actions: { ... },
85
+ * });
51
86
  */
52
87
  export declare const handleErrors: (error: unknown) => unknown;
53
88
  type SendRawRequestValues = ActionInputParameters<typeof inputs>;
54
89
  /**
55
- * This function allows you to build a generic "Raw Request" action
56
- * for a custom connector. See
57
- * https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component
90
+ * This function sends a raw HTTP request with full control over method, URL,
91
+ * headers, query parameters, and body. Used internally by `buildRawRequestAction`.
58
92
  *
59
- * @param baseUrl The base URL of the API you're integrating with
60
- * @param values An object comprising the HTTP request you'd like to make
61
- * @param authorizationHeaders Auth headers to apply to the request
62
- * @returns The response to the request
93
+ * @param baseUrl The base URL of the API you're integrating with.
94
+ * @param values An object comprising the HTTP request you'd like to make.
95
+ * @param authorizationHeaders Auth headers to apply to the request.
96
+ * @returns The Axios response to the request.
97
+ * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
98
+ * @example
99
+ * import { sendRawRequest } from "@prismatic-io/spectral/dist/clients/http";
100
+ *
101
+ * const response = await sendRawRequest(
102
+ * "https://api.acme.com/v2",
103
+ * {
104
+ * method: "GET",
105
+ * url: "/items",
106
+ * headers: [],
107
+ * queryParams: [{ key: "limit", value: "10" }],
108
+ * responseType: "json",
109
+ * },
110
+ * { Authorization: "Bearer my-token" },
111
+ * );
63
112
  */
64
113
  export declare const sendRawRequest: (baseUrl: string, values: SendRawRequestValues, authorizationHeaders?: Record<string, string>) => Promise<AxiosResponse>;
114
+ /**
115
+ * Builds a pre-configured "Raw Request" action for a custom connector.
116
+ * This action exposes a full HTTP interface (method, URL, headers, query
117
+ * params, body) so integration builders can make arbitrary API calls.
118
+ *
119
+ * @param baseUrl The base URL of the API you're integrating with.
120
+ * @param label The display label for the action. Defaults to `"Raw Request"`.
121
+ * @param description The display description for the action. Defaults to `"Issue a raw HTTP request"`.
122
+ * @returns An action definition for the raw request action.
123
+ * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
124
+ * @example
125
+ * import { buildRawRequestAction } from "@prismatic-io/spectral/dist/clients/http";
126
+ *
127
+ * // Add a raw request action to your component
128
+ * const actions = {
129
+ * listItems: action({ ... }),
130
+ * rawRequest: buildRawRequestAction("https://api.acme.com/v2"),
131
+ * };
132
+ */
65
133
  export declare const buildRawRequestAction: (baseUrl: string, label?: string, description?: string) => import("../..").ActionDefinition<{
66
134
  url: {
67
135
  label: string;
@@ -47,10 +47,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
47
47
  };
48
48
  Object.defineProperty(exports, "__esModule", { value: true });
49
49
  exports.inputs = exports.buildRawRequestAction = exports.sendRawRequest = exports.handleErrors = exports.createClient = exports.toAxiosRetryConfig = void 0;
50
- const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
51
50
  const axios_1 = __importDefault(require("axios"));
52
51
  const axios_retry_1 = __importStar(require("axios-retry"));
53
52
  const form_data_1 = __importDefault(require("form-data"));
53
+ const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
54
54
  const object_sizeof_1 = __importDefault(require("object-sizeof"));
55
55
  const __1 = require("../..");
56
56
  const util_1 = __importDefault(require("../../util"));
@@ -101,8 +101,31 @@ const toAxiosRetryConfig = (_a) => {
101
101
  };
102
102
  exports.toAxiosRetryConfig = toAxiosRetryConfig;
103
103
  /**
104
- * Creates a reusable Axios HTTP client. See
105
- * https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client
104
+ * Creates a reusable Axios HTTP client pre-configured with a base URL,
105
+ * headers, timeout, and optional retry logic. This is the recommended
106
+ * way to make HTTP requests from custom component actions.
107
+ *
108
+ * @param props Configuration for the HTTP client.
109
+ * @returns An Axios instance configured with the provided options.
110
+ * @see {@link https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client | Using the Built-in HTTP Client}
111
+ * @example
112
+ * import { createClient } from "@prismatic-io/spectral/dist/clients/http";
113
+ *
114
+ * const client = createClient({
115
+ * baseUrl: "https://api.acme.com/v2",
116
+ * headers: { Authorization: `Bearer ${accessToken}` },
117
+ * responseType: "json",
118
+ * timeout: 30000,
119
+ * debug: false,
120
+ * retryConfig: {
121
+ * retries: 3,
122
+ * retryDelay: 1000,
123
+ * useExponentialBackoff: true,
124
+ * retryAllErrors: false,
125
+ * },
126
+ * });
127
+ *
128
+ * const { data } = await client.get("/items");
106
129
  */
107
130
  const createClient = ({ baseUrl, responseType, headers, timeout, params, debug = false, retryConfig, }) => {
108
131
  const client = axios_1.default.create({
@@ -152,13 +175,25 @@ const createClient = ({ baseUrl, responseType, headers, timeout, params, debug =
152
175
  exports.createClient = createClient;
153
176
  /**
154
177
  * A global error handler that examines a thrown error and yields additional
155
- * information if the error was produced by Spectral's HTTP client. See
156
- * https://prismatic.io/docs/custom-connectors/error-handling/
157
- * and
158
- * https://prismatic.io/docs/custom-connectors/connections/#using-the-built-in-createclient-http-client
178
+ * information if the error was produced by Spectral's HTTP client. If the
179
+ * error is an Axios error, returns a structured object with the response
180
+ * `data`, `status`, and `headers`. Otherwise, returns the error as-is.
181
+ *
182
+ * Commonly used as a component-level `hooks.error` handler.
159
183
  *
160
- * @param error A JavaScript error to handle
161
- * @returns An error with data, status and headers if it was an Axios error, or the error otherwise
184
+ * @param error A JavaScript error to handle.
185
+ * @returns An error with data, status and headers if it was an Axios error, or the error otherwise.
186
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
187
+ * @example
188
+ * import { component } from "@prismatic-io/spectral";
189
+ * import { handleErrors } from "@prismatic-io/spectral/dist/clients/http";
190
+ *
191
+ * export default component({
192
+ * key: "acme",
193
+ * display: { label: "Acme", description: "Acme connector", iconPath: "icon.png" },
194
+ * hooks: { error: handleErrors },
195
+ * actions: { ... },
196
+ * });
162
197
  */
163
198
  const handleErrors = (error) => {
164
199
  if (axios_1.default.isAxiosError(error)) {
@@ -174,14 +209,28 @@ const handleErrors = (error) => {
174
209
  };
175
210
  exports.handleErrors = handleErrors;
176
211
  /**
177
- * This function allows you to build a generic "Raw Request" action
178
- * for a custom connector. See
179
- * https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component
212
+ * This function sends a raw HTTP request with full control over method, URL,
213
+ * headers, query parameters, and body. Used internally by `buildRawRequestAction`.
214
+ *
215
+ * @param baseUrl The base URL of the API you're integrating with.
216
+ * @param values An object comprising the HTTP request you'd like to make.
217
+ * @param authorizationHeaders Auth headers to apply to the request.
218
+ * @returns The Axios response to the request.
219
+ * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
220
+ * @example
221
+ * import { sendRawRequest } from "@prismatic-io/spectral/dist/clients/http";
180
222
  *
181
- * @param baseUrl The base URL of the API you're integrating with
182
- * @param values An object comprising the HTTP request you'd like to make
183
- * @param authorizationHeaders Auth headers to apply to the request
184
- * @returns The response to the request
223
+ * const response = await sendRawRequest(
224
+ * "https://api.acme.com/v2",
225
+ * {
226
+ * method: "GET",
227
+ * url: "/items",
228
+ * headers: [],
229
+ * queryParams: [{ key: "limit", value: "10" }],
230
+ * responseType: "json",
231
+ * },
232
+ * { Authorization: "Bearer my-token" },
233
+ * );
185
234
  */
186
235
  const sendRawRequest = (baseUrl_1, values_1, ...args_1) => __awaiter(void 0, [baseUrl_1, values_1, ...args_1], void 0, function* (baseUrl, values, authorizationHeaders = {}) {
187
236
  if (values.data && (!(0, isEmpty_1.default)(values.formData) || !(0, isEmpty_1.default)(values.fileData))) {
@@ -211,10 +260,29 @@ const sendRawRequest = (baseUrl_1, values_1, ...args_1) => __awaiter(void 0, [ba
211
260
  });
212
261
  });
213
262
  exports.sendRawRequest = sendRawRequest;
263
+ /**
264
+ * Builds a pre-configured "Raw Request" action for a custom connector.
265
+ * This action exposes a full HTTP interface (method, URL, headers, query
266
+ * params, body) so integration builders can make arbitrary API calls.
267
+ *
268
+ * @param baseUrl The base URL of the API you're integrating with.
269
+ * @param label The display label for the action. Defaults to `"Raw Request"`.
270
+ * @param description The display description for the action. Defaults to `"Issue a raw HTTP request"`.
271
+ * @returns An action definition for the raw request action.
272
+ * @see {@link https://prismatic.io/docs/integrations/low-code-integration-designer/raw-request-actions/#building-an-http-raw-request-action-in-your-custom-component | Raw Request Actions}
273
+ * @example
274
+ * import { buildRawRequestAction } from "@prismatic-io/spectral/dist/clients/http";
275
+ *
276
+ * // Add a raw request action to your component
277
+ * const actions = {
278
+ * listItems: action({ ... }),
279
+ * rawRequest: buildRawRequestAction("https://api.acme.com/v2"),
280
+ * };
281
+ */
214
282
  const buildRawRequestAction = (baseUrl, label = "Raw Request", description = "Issue a raw HTTP request") => (0, __1.action)({
215
283
  display: { label, description },
216
284
  inputs: Object.assign({ connection: { label: "Connection", type: "connection", required: true } }, inputs_1.inputs),
217
- perform: (context, _a) => __awaiter(void 0, void 0, void 0, function* () {
285
+ perform: (_context, _a) => __awaiter(void 0, void 0, void 0, function* () {
218
286
  var { connection } = _a, httpInputValues = __rest(_a, ["connection"]);
219
287
  const { data } = yield (0, exports.sendRawRequest)(baseUrl, httpInputValues, toAuthorizationHeaders(connection));
220
288
  return { data };
@@ -2,7 +2,7 @@
2
2
  * This module contains functions to help developers create custom components
3
3
  * to run on the Prismatic platform.
4
4
  */
5
- export { component, action, trigger, pollingTrigger, dataSource, input, connection, onPremConnection, oauth2Connection, } from "./index";
6
- export { default as util } from "./util";
7
- export * from "./types/typeExportComponent";
8
5
  export * from "./errors";
6
+ export { action, component, connection, dataSource, input, oauth2Connection, onPremConnection, pollingTrigger, trigger, } from "./index";
7
+ export * from "./types/typeExportComponent";
8
+ export { default as util } from "./util";
package/dist/component.js CHANGED
@@ -21,18 +21,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
21
21
  return (mod && mod.__esModule) ? mod : { "default": mod };
22
22
  };
23
23
  Object.defineProperty(exports, "__esModule", { value: true });
24
- exports.util = exports.oauth2Connection = exports.onPremConnection = exports.connection = exports.input = exports.dataSource = exports.pollingTrigger = exports.trigger = exports.action = exports.component = void 0;
24
+ exports.util = exports.trigger = exports.pollingTrigger = exports.onPremConnection = exports.oauth2Connection = exports.input = exports.dataSource = exports.connection = exports.component = exports.action = void 0;
25
+ __exportStar(require("./errors"), exports);
25
26
  var index_1 = require("./index");
26
- Object.defineProperty(exports, "component", { enumerable: true, get: function () { return index_1.component; } });
27
27
  Object.defineProperty(exports, "action", { enumerable: true, get: function () { return index_1.action; } });
28
- Object.defineProperty(exports, "trigger", { enumerable: true, get: function () { return index_1.trigger; } });
29
- Object.defineProperty(exports, "pollingTrigger", { enumerable: true, get: function () { return index_1.pollingTrigger; } });
28
+ Object.defineProperty(exports, "component", { enumerable: true, get: function () { return index_1.component; } });
29
+ Object.defineProperty(exports, "connection", { enumerable: true, get: function () { return index_1.connection; } });
30
30
  Object.defineProperty(exports, "dataSource", { enumerable: true, get: function () { return index_1.dataSource; } });
31
31
  Object.defineProperty(exports, "input", { enumerable: true, get: function () { return index_1.input; } });
32
- Object.defineProperty(exports, "connection", { enumerable: true, get: function () { return index_1.connection; } });
33
- Object.defineProperty(exports, "onPremConnection", { enumerable: true, get: function () { return index_1.onPremConnection; } });
34
32
  Object.defineProperty(exports, "oauth2Connection", { enumerable: true, get: function () { return index_1.oauth2Connection; } });
33
+ Object.defineProperty(exports, "onPremConnection", { enumerable: true, get: function () { return index_1.onPremConnection; } });
34
+ Object.defineProperty(exports, "pollingTrigger", { enumerable: true, get: function () { return index_1.pollingTrigger; } });
35
+ Object.defineProperty(exports, "trigger", { enumerable: true, get: function () { return index_1.trigger; } });
36
+ __exportStar(require("./types/typeExportComponent"), exports);
35
37
  var util_1 = require("./util");
36
38
  Object.defineProperty(exports, "util", { enumerable: true, get: function () { return __importDefault(util_1).default; } });
37
- __exportStar(require("./types/typeExportComponent"), exports);
38
- __exportStar(require("./errors"), exports);
@@ -18,11 +18,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
18
18
  };
19
19
  Object.defineProperty(exports, "__esModule", { value: true });
20
20
  exports.evaluate = exports.dateIsEqual = exports.dateIsBefore = exports.dateIsAfter = exports.evaluatesNotEmpty = exports.evaluatesEmpty = exports.evaluatesNull = exports.evaluatesFalse = exports.evaluatesTrue = exports.isDeepEqual = exports.isEqual = exports.parseDate = exports.contains = exports.parseValue = exports.validate = void 0;
21
- const types_1 = require("./types");
22
21
  const date_fns_1 = require("date-fns");
23
- const isEqualWith_1 = __importDefault(require("lodash/isEqualWith"));
24
22
  const isEqual_1 = __importDefault(require("lodash/isEqual"));
23
+ const isEqualWith_1 = __importDefault(require("lodash/isEqualWith"));
25
24
  const util_1 = __importDefault(require("../util"));
25
+ const types_1 = require("./types");
26
26
  const validate = (expression) => {
27
27
  if (!Array.isArray(expression)) {
28
28
  return [false, `Invalid expression syntax: '${expression}'`];
@@ -71,7 +71,7 @@ const contains = (container, containee) => {
71
71
  return container.includes(containee) || container.includes((0, exports.parseValue)(containee));
72
72
  }
73
73
  // Object attribute check (set membership).
74
- return Object.prototype.hasOwnProperty.call(container, `${containee}`);
74
+ return Object.hasOwn(container, `${containee}`);
75
75
  }
76
76
  throw new Error("Invalid arguments set to 'contains'.");
77
77
  };
package/dist/errors.d.ts CHANGED
@@ -1,11 +1,78 @@
1
1
  import { Connection } from ".";
2
+ /**
3
+ * Base error class for Spectral-specific errors. Extends the standard
4
+ * `Error` class with an `isSpectralError` flag for easy identification
5
+ * when handling errors in component hooks.
6
+ *
7
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
8
+ * @example
9
+ * import { SpectralError } from "@prismatic-io/spectral";
10
+ *
11
+ * throw new SpectralError("Something went wrong during data processing");
12
+ */
2
13
  export declare class SpectralError extends Error {
3
14
  isSpectralError: boolean;
4
15
  constructor(message: string);
5
16
  }
17
+ /**
18
+ * An error class for connection-related failures. Includes a reference to
19
+ * the `Connection` object that caused the error, so error handlers can
20
+ * inspect connection details.
21
+ *
22
+ * When thrown, the Prismatic platform will display a "Configuration Error"
23
+ * badge on the instance, signaling that the connection needs attention.
24
+ *
25
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
26
+ * @example
27
+ * import { ConnectionError } from "@prismatic-io/spectral";
28
+ *
29
+ * // Inside an action perform function
30
+ * const myAction = action({
31
+ * // ...
32
+ * perform: async (context, { connection }) => {
33
+ * try {
34
+ * // Call external API...
35
+ * } catch (err) {
36
+ * throw new ConnectionError(connection, "Invalid API credentials");
37
+ * }
38
+ * },
39
+ * });
40
+ */
6
41
  export declare class ConnectionError extends SpectralError {
7
42
  connection: Connection;
8
43
  constructor(connection: Connection, message: string);
9
44
  }
45
+ /**
46
+ * Type guard to check if an error is a `SpectralError`.
47
+ *
48
+ * @param payload The error to test.
49
+ * @returns True if `payload` is a `SpectralError`, false otherwise.
50
+ * @example
51
+ * import { isSpectralError } from "@prismatic-io/spectral";
52
+ *
53
+ * try {
54
+ * // ...
55
+ * } catch (err) {
56
+ * if (isSpectralError(err)) {
57
+ * console.log("Caught a Spectral error:", err.message);
58
+ * }
59
+ * }
60
+ */
10
61
  export declare const isSpectralError: (payload: unknown) => payload is SpectralError;
62
+ /**
63
+ * Type guard to check if an error is a `ConnectionError`.
64
+ *
65
+ * @param payload The error to test.
66
+ * @returns True if `payload` is a `ConnectionError`, false otherwise.
67
+ * @example
68
+ * import { isConnectionError } from "@prismatic-io/spectral";
69
+ *
70
+ * try {
71
+ * // ...
72
+ * } catch (err) {
73
+ * if (isConnectionError(err)) {
74
+ * console.log("Connection failed:", err.connection.key, err.message);
75
+ * }
76
+ * }
77
+ */
11
78
  export declare const isConnectionError: (payload: unknown) => payload is ConnectionError;
package/dist/errors.js CHANGED
@@ -1,6 +1,17 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.isConnectionError = exports.isSpectralError = exports.ConnectionError = exports.SpectralError = void 0;
4
+ /**
5
+ * Base error class for Spectral-specific errors. Extends the standard
6
+ * `Error` class with an `isSpectralError` flag for easy identification
7
+ * when handling errors in component hooks.
8
+ *
9
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
10
+ * @example
11
+ * import { SpectralError } from "@prismatic-io/spectral";
12
+ *
13
+ * throw new SpectralError("Something went wrong during data processing");
14
+ */
4
15
  class SpectralError extends Error {
5
16
  constructor(message) {
6
17
  super(message);
@@ -10,6 +21,30 @@ class SpectralError extends Error {
10
21
  }
11
22
  }
12
23
  exports.SpectralError = SpectralError;
24
+ /**
25
+ * An error class for connection-related failures. Includes a reference to
26
+ * the `Connection` object that caused the error, so error handlers can
27
+ * inspect connection details.
28
+ *
29
+ * When thrown, the Prismatic platform will display a "Configuration Error"
30
+ * badge on the instance, signaling that the connection needs attention.
31
+ *
32
+ * @see {@link https://prismatic.io/docs/custom-connectors/error-handling/ | Error Handling}
33
+ * @example
34
+ * import { ConnectionError } from "@prismatic-io/spectral";
35
+ *
36
+ * // Inside an action perform function
37
+ * const myAction = action({
38
+ * // ...
39
+ * perform: async (context, { connection }) => {
40
+ * try {
41
+ * // Call external API...
42
+ * } catch (err) {
43
+ * throw new ConnectionError(connection, "Invalid API credentials");
44
+ * }
45
+ * },
46
+ * });
47
+ */
13
48
  class ConnectionError extends SpectralError {
14
49
  constructor(connection, message) {
15
50
  super(message);
@@ -17,10 +52,42 @@ class ConnectionError extends SpectralError {
17
52
  }
18
53
  }
19
54
  exports.ConnectionError = ConnectionError;
55
+ /**
56
+ * Type guard to check if an error is a `SpectralError`.
57
+ *
58
+ * @param payload The error to test.
59
+ * @returns True if `payload` is a `SpectralError`, false otherwise.
60
+ * @example
61
+ * import { isSpectralError } from "@prismatic-io/spectral";
62
+ *
63
+ * try {
64
+ * // ...
65
+ * } catch (err) {
66
+ * if (isSpectralError(err)) {
67
+ * console.log("Caught a Spectral error:", err.message);
68
+ * }
69
+ * }
70
+ */
20
71
  const isSpectralError = (payload) => Boolean(payload &&
21
72
  typeof payload === "object" &&
22
73
  "isSpectralError" in payload &&
23
74
  payload.isSpectralError === true);
24
75
  exports.isSpectralError = isSpectralError;
76
+ /**
77
+ * Type guard to check if an error is a `ConnectionError`.
78
+ *
79
+ * @param payload The error to test.
80
+ * @returns True if `payload` is a `ConnectionError`, false otherwise.
81
+ * @example
82
+ * import { isConnectionError } from "@prismatic-io/spectral";
83
+ *
84
+ * try {
85
+ * // ...
86
+ * } catch (err) {
87
+ * if (isConnectionError(err)) {
88
+ * console.log("Connection failed:", err.connection.key, err.message);
89
+ * }
90
+ * }
91
+ */
25
92
  const isConnectionError = (payload) => (0, exports.isSpectralError)(payload) && "connection" in payload;
26
93
  exports.isConnectionError = isConnectionError;
@@ -13,17 +13,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
13
13
  };
14
14
  Object.defineProperty(exports, "__esModule", { value: true });
15
15
  exports.runMain = void 0;
16
- const _1 = require(".");
17
- const createFlagHelpText_1 = require("../utils/createFlagHelpText");
18
- const getFlagBooleanValue_1 = require("../utils/getFlagBooleanValue");
19
16
  const node_fs_1 = require("node:fs");
17
+ const node_path_1 = __importDefault(require("node:path"));
20
18
  const createActions_1 = require("../componentManifest/createActions");
21
- const createTriggers_1 = require("../componentManifest/createTriggers");
22
19
  const createConnections_1 = require("../componentManifest/createConnections");
23
20
  const createDataSources_1 = require("../componentManifest/createDataSources");
24
- const node_path_1 = __importDefault(require("node:path"));
21
+ const createTriggers_1 = require("../componentManifest/createTriggers");
25
22
  const removeComponentManifest_1 = require("../componentManifest/removeComponentManifest");
23
+ const createFlagHelpText_1 = require("../utils/createFlagHelpText");
26
24
  const createTemplate_1 = require("../utils/createTemplate");
25
+ const getFlagBooleanValue_1 = require("../utils/getFlagBooleanValue");
26
+ const _1 = require(".");
27
27
  const runMain = (process) => __awaiter(void 0, void 0, void 0, function* () {
28
28
  const args = process.argv.slice(2);
29
29
  const componentKey = args[0];
@@ -1,4 +1,4 @@
1
- import type { Inputs, ConfigVarResultCollection, TriggerPayload, TriggerResult } from "../../types";
1
+ import type { ConfigVarResultCollection, Inputs, TriggerPayload, TriggerResult } from "../../types";
2
2
  import { FormattedAction, FormattedDataSource, FormattedTrigger } from "./types";
3
3
  export declare const fetchComponentDataForManifest: <TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>>({ componentKey, isPrivate, }: {
4
4
  componentKey: string;
@@ -1,4 +1,6 @@
1
1
  "use strict";
2
+ /* eslint-disable @typescript-eslint/no-var-requires */
3
+ /* eslint-disable @typescript-eslint/no-unsafe-member-access */
2
4
  var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
5
  function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
6
  return new (P || (P = Promise))(function (resolve, reject) {
@@ -13,15 +15,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
13
15
  };
14
16
  Object.defineProperty(exports, "__esModule", { value: true });
15
17
  exports.runMain = void 0;
16
- /* eslint-disable @typescript-eslint/no-var-requires */
17
- /* eslint-disable @typescript-eslint/no-unsafe-member-access */
18
- const path_1 = __importDefault(require("path"));
19
18
  const fs_extra_1 = require("fs-extra");
20
- const index_1 = require("./index");
19
+ const path_1 = __importDefault(require("path"));
20
+ const util_1 = require("../../util");
21
21
  const createFlagHelpText_1 = require("../utils/createFlagHelpText");
22
- const getFlagStringValue_1 = require("../utils/getFlagStringValue");
23
22
  const getFlagBooleanValue_1 = require("../utils/getFlagBooleanValue");
24
- const util_1 = require("../../util");
23
+ const getFlagStringValue_1 = require("../utils/getFlagStringValue");
24
+ const index_1 = require("./index");
25
25
  const runMain = (process) => __awaiter(void 0, void 0, void 0, function* () {
26
26
  var _a, _b;
27
27
  const componentDir = process.cwd();
@@ -1,5 +1,5 @@
1
+ import { ConfigVarResultCollection, Inputs, TriggerPayload, TriggerResult } from "../../types";
1
2
  import type { ComponentForManifest } from "../cniComponentManifest/types";
2
- import { Inputs, ConfigVarResultCollection, TriggerPayload, TriggerResult } from "../../types";
3
3
  interface CreateActionsProps<TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>> {
4
4
  component: ComponentForManifest<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult>;
5
5
  dryRun: boolean;
@@ -14,12 +14,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
14
14
  Object.defineProperty(exports, "__esModule", { value: true });
15
15
  exports.createActions = void 0;
16
16
  const path_1 = __importDefault(require("path"));
17
- const getInputs_1 = require("./getInputs");
18
- const getImports_1 = require("./getImports");
19
- const helpers_1 = require("./helpers");
17
+ const createImport_1 = require("../utils/createImport");
20
18
  const createTemplate_1 = require("../utils/createTemplate");
21
19
  const createTypeInterface_1 = require("../utils/createTypeInterface");
22
- const createImport_1 = require("../utils/createImport");
20
+ const getImports_1 = require("./getImports");
21
+ const getInputs_1 = require("./getInputs");
22
+ const helpers_1 = require("./helpers");
23
23
  const createActions = (_a) => __awaiter(void 0, [_a], void 0, function* ({ component, dryRun, verbose, sourceDir, destinationDir, }) {
24
24
  var _b, _c;
25
25
  if (verbose) {
@@ -1,5 +1,5 @@
1
+ import { ConfigVarResultCollection, Inputs, TriggerPayload, TriggerResult } from "../../types";
1
2
  import type { ComponentForManifest } from "../cniComponentManifest/types";
2
- import { Inputs, ConfigVarResultCollection, TriggerPayload, TriggerResult } from "../../types";
3
3
  interface CreateConnectionsProps<TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>> {
4
4
  component: ComponentForManifest<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult>;
5
5
  dryRun: boolean;
@@ -14,12 +14,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
14
14
  Object.defineProperty(exports, "__esModule", { value: true });
15
15
  exports.createConnections = void 0;
16
16
  const path_1 = __importDefault(require("path"));
17
- const getInputs_1 = require("./getInputs");
18
- const getImports_1 = require("./getImports");
19
- const helpers_1 = require("./helpers");
17
+ const createImport_1 = require("../utils/createImport");
20
18
  const createTemplate_1 = require("../utils/createTemplate");
21
19
  const createTypeInterface_1 = require("../utils/createTypeInterface");
22
- const createImport_1 = require("../utils/createImport");
20
+ const getImports_1 = require("./getImports");
21
+ const getInputs_1 = require("./getInputs");
22
+ const helpers_1 = require("./helpers");
23
23
  const createConnections = (_a) => __awaiter(void 0, [_a], void 0, function* ({ component, dryRun, verbose, sourceDir, destinationDir, reusableConnectionStableKeys = [], }) {
24
24
  var _b, _c;
25
25
  if (verbose) {
@@ -1,5 +1,5 @@
1
+ import { ConfigVarResultCollection, Inputs, TriggerPayload, TriggerResult } from "../../types";
1
2
  import type { ComponentForManifest } from "../cniComponentManifest/types";
2
- import { Inputs, ConfigVarResultCollection, TriggerPayload, TriggerResult } from "../../types";
3
3
  interface CreateDataSourcesProps<TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>> {
4
4
  component: ComponentForManifest<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult>;
5
5
  dryRun: boolean;
@@ -14,12 +14,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
14
14
  Object.defineProperty(exports, "__esModule", { value: true });
15
15
  exports.createDataSources = void 0;
16
16
  const path_1 = __importDefault(require("path"));
17
- const getInputs_1 = require("./getInputs");
18
- const getImports_1 = require("./getImports");
19
- const helpers_1 = require("./helpers");
17
+ const createImport_1 = require("../utils/createImport");
20
18
  const createTemplate_1 = require("../utils/createTemplate");
21
19
  const createTypeInterface_1 = require("../utils/createTypeInterface");
22
- const createImport_1 = require("../utils/createImport");
20
+ const getImports_1 = require("./getImports");
21
+ const getInputs_1 = require("./getInputs");
22
+ const helpers_1 = require("./helpers");
23
23
  const createDataSources = (_a) => __awaiter(void 0, [_a], void 0, function* ({ component, dryRun, verbose, sourceDir, destinationDir, }) {
24
24
  var _b, _c;
25
25
  if (verbose) {