[prototype] Import declarative webhooks

[shauns]

WHY are these changes introduced?

Make it easier to start using declarative webhooks by helping you write the TOML your app might need.

WHAT is this pull request doing?

• New capability to connect to admin on behalf of the current app (incl. GraphQL codegen 🪄 )
• Use this to list current webhooks and output some TOML

How to test your changes?

• Create an app, install it, create some webhook subscriptions via the API
• Run app import-extensions and choose webhooks. You should get the TOML equivalent of what you set up.

Post-release steps

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[github-actions]

Thanks for your contribution!

Depending on what you are working on, you may want to request a review from a Shopify team:

• Themes: @shopify/advanced-edits
• UI extensions: @shopify/ui-extensions-cli
  • Checkout UI extensions: @shopify/checkout-ui-extensions-api-stewardship
• Hydrogen: @shopify/hydrogen
• Other: @shopify/app-inner-loop

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/api/admin-as-app.d.ts

import { AdminSession } from '../session.js';
import { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { Variables } from 'graphql-request';
/**
 * Executes a GraphQL query against the Admin API on behalf of the app. Uses typed documents.
 *
 * @param query - GraphQL query to execute.
 * @param session - Admin session.
 * @param apiVersion - API version, e.g. '2024-07'.
 * @param variables - GraphQL variables to pass to the query.
 * @returns The response of the query of generic type <TResult>.
 */
export declare function adminAsAppRequest<TResult, TVariables extends Variables>(query: TypedDocumentNode<TResult, TVariables>, session: AdminSession, apiVersion: string, variables?: TVariables): Promise<TResult>;

Existing type declarations

packages/cli-kit/dist/public/node/session.d.ts

@@ -54,6 +54,17 @@ export declare function ensureAuthenticatedStorefront(scopes?: string[], passwor
  * @returns The access token for the Admin API.
  */
 export declare function ensureAuthenticatedAdmin(store: string, scopes?: string[], forceRefresh?: boolean, options?: EnsureAuthenticatedAdditionalOptions): Promise<AdminSession>;
+/**
+ * Ensure that we have a valid Admin session for the given store, acting on behalf of the app.
+ *
+ * This will fail if the app has not already been installed.
+ *
+ * @param storeFqdn - Store fqdn to request auth for.
+ * @param apiKey - API key for the app.
+ * @param apiSecret - API secret for the app.
+ * @returns The access token for the Admin API.
+ */
+export declare function ensureAuthenticatedAdminAsApp(storeFqdn: string, apiKey: string, apiSecret: string): Promise<AdminSession>;
 /**
  * Ensure that we have a valid session to access the Theme API.
  * If a password is provided, that token will be used against Theme Access API.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	72.93% (-0.08% 🔻)	8442/11576
🟡	Branches	69.44% (-0.12% 🔻)	4106/5913
🟡	Functions	71.8% (+0.05% 🔼)	2192/3053
🟡	Lines	73.26% (-0.1% 🔻)	7987/10903

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / list-webhook-subscriptions.ts	100%	100%	100%	100%
🔴	... / import-declarative-webhooks.ts	61.11%	46.67%	92.31%	58.82%
🔴	... / admin-as-app.ts	0%	100%	0%	0%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / import-extensions.ts	93.75% (-6.25% 🔻)	75% (-8.33% 🔻)	100%	93.55% (-6.45% 🔻)
🟢	... / ConcurrentOutput.tsx	98.39% (-1.61% 🔻)	90.91% (-4.55% 🔻)	100%	98.33% (-1.67% 🔻)

Test suite run success

1891 tests passing in 860 suites.

Report generated by 🧪jest coverage report action from d51b164