@atlaskit/link-client-extension 8.0.0 → 8.0.1

package/dist/esm/services/use-integration-actions-client/mocks.js

@@ -0,0 +1,85 @@
+/**
+ * Mock AGG `actions { execute }` responses, based on what the ASIMO-5527 spike saw
+ * on staging.
+ */
+
+export var mockExecuteIntegrationActionSuccessResponse = {
+  data: {
+    actions: {
+      execute: {
+        status: 200,
+        outputs: {
+          entities: {
+            comments: [{
+              id: 'comment-1',
+              content: 'Looks good to me',
+              author: {
+                displayName: 'Jane Smith'
+              },
+              createdTime: '2026-10-27T01:00:00.000Z'
+            }]
+          }
+        }
+      }
+    }
+  }
+};
+export var mockAuthUrl = 'https://id.atlassian.com/outboundAuth/start?key=google-drive';
+
+/** IS returns consent errors in `outputs.errors` with HTTP 200 and no GraphQL `errors`. */
+export var mockExecuteIntegrationActionConsentRequiredResponse = {
+  data: {
+    actions: {
+      execute: {
+        status: 401,
+        outputs: {
+          errors: [{
+            message: 'User consent is required to access this integration',
+            statusCode: 401,
+            extensions: {
+              errorType: 'USER_CONSENT_REQUIRED',
+              errorCategory: 'AUTH',
+              retryable: false,
+              authUrl: mockAuthUrl
+            }
+          }]
+        }
+      }
+    }
+  }
+};
+export var mockExecuteIntegrationActionOperationFailureResponse = {
+  data: {
+    actions: {
+      execute: {
+        status: 404,
+        outputs: {
+          errors: [{
+            message: 'File not found',
+            statusCode: 404,
+            extensions: {
+              errorType: 'NOT_FOUND',
+              errorCategory: 'CLIENT',
+              retryable: false
+            }
+          }]
+        }
+      }
+    }
+  }
+};
+export var mockExecuteIntegrationActionGraphQLErrorResponse = {
+  data: {
+    actions: {
+      execute: null
+    }
+  },
+  errors: [{
+    message: 'Action not found for filter',
+    path: ['actions', 'execute'],
+    extensions: {
+      classification: 'DataFetchingException',
+      statusCode: 400
+    }
+  }]
+};

package/dist/esm/services/use-integration-actions-client/parse-execute-integration-action-response.js

@@ -0,0 +1,161 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _typeof from "@babel/runtime/helpers/typeof";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+import { GENERIC_GRAPHQL_ERROR_MESSAGE, GENERIC_OPERATION_ERROR_MESSAGE, USER_CONSENT_REQUIRED } from './constants';
+import { IntegrationActionError } from './integration-action-error';
+var isRecord = function isRecord(value) {
+  return _typeof(value) === 'object' && value !== null && !Array.isArray(value);
+};
+var isSuccessStatus = function isSuccessStatus(status) {
+  return status >= 200 && status < 300;
+};
+var getStringExtension = function getStringExtension(extensions, key) {
+  var value = extensions === null || extensions === void 0 ? void 0 : extensions[key];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+};
+
+/**
+ * Returns `authUrl` from the extensions only if it's an absolute `https:` URL, so a malformed or
+ * unsafe value (e.g. `javascript:`) is never handed to the UI to open.
+ */
+var getAuthUrl = function getAuthUrl(extensions) {
+  var value = getStringExtension(extensions, 'authUrl');
+  if (!value) {
+    return undefined;
+  }
+  try {
+    return new URL(value).protocol === 'https:' ? value : undefined;
+  } catch (_unused) {
+    return undefined;
+  }
+};
+
+/** Normalises an entry of `outputs.errors`, which IS doesn't guarantee is well-formed. */
+var toOperationErrorEntry = function toOperationErrorEntry(error) {
+  if (typeof error === 'string') {
+    return {
+      message: error || GENERIC_OPERATION_ERROR_MESSAGE
+    };
+  }
+  if (!isRecord(error)) {
+    return {
+      message: GENERIC_OPERATION_ERROR_MESSAGE
+    };
+  }
+  return _objectSpread(_objectSpread({
+    message: typeof error.message === 'string' && error.message !== '' ? error.message : GENERIC_OPERATION_ERROR_MESSAGE
+  }, isRecord(error.extensions) ? {
+    extensions: error.extensions
+  } : {}), typeof error.statusCode === 'number' ? {
+    statusCode: error.statusCode
+  } : {});
+};
+
+/** Normalises an entry of the GraphQL `errors` array, which may be malformed. */
+var toGraphQLErrorEntry = function toGraphQLErrorEntry(error) {
+  if (!isRecord(error)) {
+    return {
+      message: typeof error === 'string' && error ? error : GENERIC_GRAPHQL_ERROR_MESSAGE
+    };
+  }
+  return _objectSpread(_objectSpread({
+    message: typeof error.message === 'string' && error.message !== '' ? error.message : GENERIC_GRAPHQL_ERROR_MESSAGE
+  }, isRecord(error.extensions) ? {
+    extensions: error.extensions
+  } : {}), Array.isArray(error.path) ? {
+    path: error.path
+  } : {});
+};
+
+/** A non-empty `outputs.errors` always means the action failed, even if the entries are malformed. */
+var getOperationErrors = function getOperationErrors(outputs) {
+  var errors = isRecord(outputs) ? outputs.errors : undefined;
+  if (!Array.isArray(errors) || errors.length === 0) {
+    return undefined;
+  }
+  return errors.map(toOperationErrorEntry);
+};
+var toOperationError = function toOperationError(operationErrors, status) {
+  var _error$extensions, _error$statusCode;
+  var consentError = operationErrors.find(function (error) {
+    return getStringExtension(error.extensions, 'errorType') === USER_CONSENT_REQUIRED || !!getAuthUrl(error.extensions);
+  });
+  var error = consentError !== null && consentError !== void 0 ? consentError : operationErrors[0];
+  var authUrl = getAuthUrl(consentError === null || consentError === void 0 ? void 0 : consentError.extensions);
+  var retryable = (_error$extensions = error.extensions) === null || _error$extensions === void 0 ? void 0 : _error$extensions.retryable;
+  var options = {
+    authUrl: authUrl,
+    errorType: getStringExtension(error.extensions, 'errorType'),
+    retryable: typeof retryable === 'boolean' ? retryable : undefined,
+    statusCode: (_error$statusCode = error.statusCode) !== null && _error$statusCode !== void 0 ? _error$statusCode : status,
+    operationErrors: operationErrors
+  };
+  if (consentError && authUrl) {
+    return new IntegrationActionError('consent-required', error.message, options);
+  }
+  return new IntegrationActionError('operation', error.message, options);
+};
+var toGraphQLError = function toGraphQLError(graphQLErrors, statusCode) {
+  var authUrl = graphQLErrors.map(function (error) {
+    return getAuthUrl(error.extensions);
+  }).find(function (url) {
+    return !!url;
+  });
+  var errorType = graphQLErrors.map(function (error) {
+    var _getStringExtension;
+    return (_getStringExtension = getStringExtension(error.extensions, 'errorType')) !== null && _getStringExtension !== void 0 ? _getStringExtension : getStringExtension(error.extensions, 'classification');
+  }).find(function (type) {
+    return !!type;
+  });
+  var message = graphQLErrors.map(function (error) {
+    return error.message;
+  }).join('; ');
+  var options = {
+    authUrl: authUrl,
+    errorType: errorType,
+    statusCode: statusCode,
+    graphQLErrors: graphQLErrors
+  };
+  if (authUrl) {
+    return new IntegrationActionError('consent-required', message, options);
+  }
+  return new IntegrationActionError('graphql', message, options);
+};
+
+/**
+ * Turns an AGG response body into the action response, or throws an `IntegrationActionError`.
+ *
+ * Errors are checked in this order:
+ * 1. IS operation errors in `outputs.errors` (consent required, or the action failed).
+ * 2. GraphQL `errors`, even with a partial `execute` result. The mutation only selects
+ *    `actions.execute`, so any GraphQL error relates to the action.
+ * 3. A missing `execute` result.
+ * 4. A non-2xx `status` from IS.
+ */
+export var parseExecuteIntegrationActionResponse = function parseExecuteIntegrationActionResponse(body, httpStatus) {
+  var _body$data;
+  var execute = body === null || body === void 0 || (_body$data = body.data) === null || _body$data === void 0 || (_body$data = _body$data.actions) === null || _body$data === void 0 ? void 0 : _body$data.execute;
+  var graphQLErrors = Array.isArray(body === null || body === void 0 ? void 0 : body.errors) && body.errors.length ? body.errors.map(toGraphQLErrorEntry) : undefined;
+  var operationErrors = getOperationErrors(execute === null || execute === void 0 ? void 0 : execute.outputs);
+  if (operationErrors !== null && operationErrors !== void 0 && operationErrors.length) {
+    throw toOperationError(operationErrors, execute === null || execute === void 0 ? void 0 : execute.status);
+  }
+  if (graphQLErrors) {
+    throw toGraphQLError(graphQLErrors, httpStatus);
+  }
+  if (!execute) {
+    throw new IntegrationActionError('graphql', 'No action result returned', {
+      statusCode: httpStatus
+    });
+  }
+  if (typeof execute.status === 'number' && !isSuccessStatus(execute.status)) {
+    throw new IntegrationActionError('operation', "Action failed with status ".concat(execute.status), {
+      statusCode: execute.status
+    });
+  }
+  return {
+    status: execute.status,
+    outputs: execute.outputs
+  };
+};

package/dist/types/services/use-integration-actions-client/build-request-headers.d.ts

@@ -0,0 +1,15 @@
+import type { ProductType } from '@atlaskit/linking-common/types';
+type BuildRequestHeadersOptions = {
+    /** Cloud ID of the current site. Sent as `tenantId`, or `null` when unknown. */
+    cloudId?: string;
+    /** Product hosting the Smart Link, mapped to a GTM product name. */
+    product?: ProductType;
+};
+/**
+ * The `atl-attribution` header AGG asks frontend clients to send for metrics attribution:
+ * JSON with `tenantId`, `product` (when known) and `service`.
+ *
+ * See https://hello.atlassian.net/wiki/spaces/aggp/pages/5954141702
+ */
+export declare const buildRequestHeaders: ({ cloudId, product, }: BuildRequestHeadersOptions) => Record<string, string>;
+export {};

package/dist/types/services/use-integration-actions-client/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const EXECUTE_INTEGRATION_ACTION_OPERATION_NAME = "LinkClientExtension_ExecuteIntegrationAction";
+export declare const EXECUTE_INTEGRATION_ACTION_MUTATION: string;
+export declare const USER_CONSENT_REQUIRED = "USER_CONSENT_REQUIRED";
+/** `service` value for the AGG `atl-attribution` header. */
+export declare const ATTRIBUTION_SERVICE = "link-client-extension";
+/** Fallback message when IS reports an error without one. */
+export declare const GENERIC_OPERATION_ERROR_MESSAGE = "Action failed";
+/** Fallback message when AGG returns a GraphQL error without one. */
+export declare const GENERIC_GRAPHQL_ERROR_MESSAGE = "GraphQL error";

package/dist/types/services/use-integration-actions-client/get-agg-url.d.ts

@@ -0,0 +1,13 @@
+import type { EnvironmentsKeys } from '@atlaskit/linking-common/types';
+/**
+ * AGG endpoint for the CardClient's environment.
+ * - No envKey (running inside a product): same-origin `/gateway/api/graphql`. On the server there
+ *   is no `window`, so this is relative and requests fail with an `http` error instead of crashing.
+ * - `custom`: `baseUrlOverride` is a full object resolver URL (e.g. a direct service URL for SSR),
+ *   so we can't build an AGG URL from it. Use the relative edge proxy path instead, the same
+ *   fallback `getResolverUrl` uses.
+ * - Other envKeys (e.g. `stg` in examples): the Stargate base URL for that environment + `/graphql`,
+ *   e.g. `https://pug.jira-dev.com/gateway/api/graphql`.
+ * The operation name is added as a query param so requests are easy to identify.
+ */
+export declare const getAggUrl: (envKey?: EnvironmentsKeys) => string;

package/dist/types/services/use-integration-actions-client/index.d.ts

@@ -0,0 +1,32 @@
+import type CardClient from '@atlaskit/link-provider/client';
+import type { ProductType } from '@atlaskit/linking-common/types';
+import type { ExecuteIntegrationActionRequest, ExecuteIntegrationActionResponse } from './types';
+type UseIntegrationActionsClientOptions = {
+    /** Product hosting the Smart Link. Sent to AGG in the `atl-attribution` header. */
+    product?: ProductType;
+};
+/**
+ * useIntegrationActionsClient
+ *
+ * Runs Integrations Service (IS) actions on 3P resources (e.g. listing or adding Google Docs
+ * comments) through the AGG `actions { execute }` mutation. Uses a plain fetch rather than Relay,
+ * so it works in any host that provides a CardClient.
+ *
+ * `executeAction` resolves with the action's `outputs`. It throws an `IntegrationActionError` when:
+ * - the user needs to connect their 3P account (`kind: 'consent-required'`, with `authUrl`)
+ * - IS reports the action failed (`kind: 'operation'`)
+ * - AGG returns GraphQL errors (`kind: 'graphql'`)
+ * - the request fails (`kind: 'http'`)
+ *
+ * Each request sends the AGG metrics attribution header (`atl-attribution`), using
+ * `actionInput.cloudId` as the tenant.
+ *
+ * Call `executeAction` from effects or event handlers, not during render (it doesn't run in SSR).
+ *
+ * @param cardClient used to pick the AGG endpoint for the environment
+ * @param options.product product hosting the Smart Link, for metrics attribution
+ */
+export declare const useIntegrationActionsClient: (cardClient: CardClient, { product }?: UseIntegrationActionsClientOptions) => {
+    executeAction: <TOutputs = unknown>(data: ExecuteIntegrationActionRequest) => Promise<ExecuteIntegrationActionResponse<TOutputs>>;
+};
+export {};

package/dist/types/services/use-integration-actions-client/integration-action-error.d.ts

@@ -0,0 +1,26 @@
+import type { IntegrationActionErrorKind, IntegrationActionGraphQLError, IntegrationActionOperationError } from './types';
+export type IntegrationActionErrorOptions = {
+    authUrl?: string;
+    errorType?: string;
+    graphQLErrors?: IntegrationActionGraphQLError[];
+    operationErrors?: IntegrationActionOperationError[];
+    /** The underlying error, e.g. the network `TypeError` for a failed fetch. */
+    originalError?: unknown;
+    retryable?: boolean;
+    statusCode?: number;
+};
+/** Thrown by `executeAction` when an action can't be run or fails. */
+export declare class IntegrationActionError extends Error {
+    readonly kind: IntegrationActionErrorKind;
+    /** Set when `kind` is `consent-required`: where the user can connect their 3P account. */
+    readonly authUrl?: string;
+    readonly errorType?: string;
+    readonly retryable?: boolean;
+    /** HTTP status, or the status IS reported for the action. */
+    readonly statusCode?: number;
+    readonly graphQLErrors?: IntegrationActionGraphQLError[];
+    readonly operationErrors?: IntegrationActionOperationError[];
+    /** The underlying error, when the request itself failed. */
+    readonly originalError?: unknown;
+    constructor(kind: IntegrationActionErrorKind, message: string, options?: IntegrationActionErrorOptions);
+}

package/dist/types/services/use-integration-actions-client/mocks.d.ts

@@ -0,0 +1,11 @@
+import type { ExecuteIntegrationActionGraphQLResponse } from './types';
+/**
+ * Mock AGG `actions { execute }` responses, based on what the ASIMO-5527 spike saw
+ * on staging.
+ */
+export declare const mockExecuteIntegrationActionSuccessResponse: ExecuteIntegrationActionGraphQLResponse;
+export declare const mockAuthUrl = "https://id.atlassian.com/outboundAuth/start?key=google-drive";
+/** IS returns consent errors in `outputs.errors` with HTTP 200 and no GraphQL `errors`. */
+export declare const mockExecuteIntegrationActionConsentRequiredResponse: ExecuteIntegrationActionGraphQLResponse;
+export declare const mockExecuteIntegrationActionOperationFailureResponse: ExecuteIntegrationActionGraphQLResponse;
+export declare const mockExecuteIntegrationActionGraphQLErrorResponse: ExecuteIntegrationActionGraphQLResponse;

package/dist/types/services/use-integration-actions-client/parse-execute-integration-action-response.d.ts

@@ -0,0 +1,12 @@
+import type { ExecuteIntegrationActionGraphQLResponse, ExecuteIntegrationActionResponse } from './types';
+/**
+ * Turns an AGG response body into the action response, or throws an `IntegrationActionError`.
+ *
+ * Errors are checked in this order:
+ * 1. IS operation errors in `outputs.errors` (consent required, or the action failed).
+ * 2. GraphQL `errors`, even with a partial `execute` result. The mutation only selects
+ *    `actions.execute`, so any GraphQL error relates to the action.
+ * 3. A missing `execute` result.
+ * 4. A non-2xx `status` from IS.
+ */
+export declare const parseExecuteIntegrationActionResponse: <TOutputs = unknown>(body: ExecuteIntegrationActionGraphQLResponse | undefined, httpStatus?: number) => ExecuteIntegrationActionResponse<TOutputs>;

package/dist/types/services/use-integration-actions-client/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Types for executing Integrations Service (IS) actions through the Atlassian GraphQL Gateway (AGG)
+ * `actions { execute }` mutation.
+ *
+ * Internal for now. Move these to `@atlaskit/linking-types` (e.g. an `integration-actions` entry)
+ * once there is a consumer outside this package.
+ */
+/** Mirrors AGG `ActionsAuthType`. */
+export type IntegrationActionAuthType = 
+/** Runs with a user in context. */
+'THREE_LEGGED'
+/** Runs without a user in context. */
+ | 'TWO_LEGGED';
+/** Selects which action IS should run. Mirrors AGG `ActionsExecuteActionFilter`. */
+export type IntegrationActionFilter = {
+    /** Run the action with this ARI. Don't set `actionId` as well. */
+    actionAri?: string;
+    /**
+     * Run the action with this ID, e.g. for custom-alias actions with
+     * `actionTypeKey: 'atlassian::custom:action'`. Don't set `actionAri` as well.
+     */
+    actionId?: string;
+    /** Only run actions that support these auth types. */
+    authType?: IntegrationActionAuthType[];
+    /** Only run the action that matches this extension ARI. */
+    extensionAri?: string;
+    /** Only run actions for this first-party integration, e.g. `google-drive` or `github`. */
+    integrationKey?: string;
+    /** Only run actions for this OAuth client. */
+    oauthClientId?: string;
+    /** Only run actions for this provider ARI. */
+    providerAri?: string;
+    /** Only run actions for this provider ID. */
+    providerId?: string;
+};
+/** The resource the action runs against. Mirrors AGG `ActionsExecuteTargetInput`. */
+export type IntegrationActionTarget = {
+    ari?: string;
+    /** Provider-specific IDs that identify the resource. */
+    ids?: Record<string, unknown>;
+    url?: string;
+};
+/** Mirrors AGG `ActionsExecuteActionInput`. */
+export type IntegrationActionInput = {
+    /** Cloud ID of the site to run the action on. */
+    cloudId?: string;
+    /** Action-specific inputs, e.g. `{ fileId, content }` for adding a Google Docs comment. */
+    inputs?: Record<string, unknown>;
+    /** Runtime metadata from the caller, kept separate from the action inputs. */
+    meta?: Record<string, unknown>;
+    target?: IntegrationActionTarget;
+};
+export type ExecuteIntegrationActionRequest = {
+    actionInput: IntegrationActionInput;
+    /**
+     * Standard action type key, or `atlassian::custom:action` for custom-alias actions
+     * (set `filter.actionId` as well).
+     */
+    actionTypeKey?: string;
+    filter: IntegrationActionFilter;
+    workspace?: string;
+};
+export type ExecuteIntegrationActionResponse<TOutputs = unknown> = {
+    /** Outputs from the app that ran the action. The shape depends on the action. */
+    outputs: TOutputs;
+    /** Status IS reports for the action (HTTP-like, e.g. 200). */
+    status?: number;
+};
+/** A GraphQL error from AGG, in the top-level `errors` array. */
+export type IntegrationActionGraphQLError = {
+    extensions?: Record<string, unknown>;
+    message: string;
+    path?: (string | number)[];
+};
+/**
+ * An error IS reports in `data.actions.execute.outputs.errors`.
+ * These come back with HTTP 200 and no GraphQL `errors`.
+ */
+export type IntegrationActionOperationError = {
+    extensions?: {
+        [key: string]: unknown;
+        /** URL where the user can connect, or reconnect, their 3P account. */
+        authUrl?: string;
+        errorCategory?: string;
+        /** e.g. `USER_CONSENT_REQUIRED` */
+        errorType?: string;
+        retryable?: boolean;
+    };
+    message: string;
+    statusCode?: number;
+};
+export type IntegrationActionErrorKind = 
+/** The user must connect, or reconnect, their 3P account. See `authUrl`. */
+'consent-required'
+/** IS ran the action and it failed. */
+ | 'operation'
+/** AGG returned GraphQL errors, or the response was malformed. */
+ | 'graphql'
+/** The request failed: non-2xx response, network error, or non-JSON body. */
+ | 'http';
+/** Raw AGG response body for the execute mutation. */
+export type ExecuteIntegrationActionGraphQLResponse = {
+    data?: {
+        actions?: {
+            execute?: {
+                outputs?: unknown;
+                status?: number;
+            } | null;
+        } | null;
+    } | null;
+    errors?: IntegrationActionGraphQLError[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/link-client-extension",
-	"version": "8.0.0",
+	"version": "8.0.1",
 	"description": "Extension methods for linking platform client",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -15,7 +15,7 @@
 				"importSpecifierName": "isReactCompilerActivePlatform"
 			}
 		},
-		"team": "Navigation Experiences - Linking Platform",
+		"team": "Rovo Growth - Smartlinks",
 		"website": {
 			"tags": [
 				"platform-labs"
@@ -31,9 +31,9 @@
 	"sideEffects": false,
 	"atlaskit:src": "src/index.ts",
 	"dependencies": {
-		"@atlaskit/json-ld-types": "^2.0.0",
+		"@atlaskit/json-ld-types": "^2.1.0",
 		"@atlaskit/linking-common": "^13.0.0",
-		"@atlaskit/linking-types": "^16.0.0",
+		"@atlaskit/linking-types": "^16.1.0",
 		"@atlaskit/platform-feature-flags": "^2.2.0",
 		"@atlaskit/react-compiler-gating": "^0.2.0",
 		"@babel/runtime": "^7.0.0",
@@ -44,13 +44,13 @@
 		"react": "^18.2.0"
 	},
 	"devDependencies": {
+		"@atlaskit/link-provider": "^6.0.0",
 		"@atlaskit/link-test-helpers": "^11.2.0",
 		"@atlassian/feature-flags-test-utils": "^1.3.0",
 		"@atlassian/structured-docs-types": "workspace:^",
 		"@testing-library/react": "^16.3.0",
 		"react": "^18.2.0",
-		"react-dom": "^18.2.0",
-		"wait-for-expect": "^1.2.0"
+		"react-dom": "^18.2.0"
 	},
 	"compassUnitTestMetricSourceId": "ari:cloud:compass:a436116f-02ce-4520-8fbb-7301462a1674:metric-source/c5751cc6-3513-4070-9deb-af31e86aed34/cf4080bb-133c-425e-bf40-17e725f5add5"
 }