Make protocol TypeScript declarations emittable in isolation

platforms/web/package.json

@@ -95,7 +95,7 @@
     "oxlint": "^1.62.0",
     "publint": "^0.3.12",
     "typescript": "5.9.3",
-    "vite": "^8.0.0",
+    "vite": "^8.3.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.1.0"
   },

platforms/web/vite.config.ts

@@ -6,8 +6,8 @@ import browserslistToEsbuild from 'browserslist-to-esbuild';
 import {defineConfig} from 'vitest/config';
 import dts from 'vite-plugin-dts';
 
-import packageJson from './package.json';
-import {appendTagNameMap, createTagNameCollector} from './scripts/tag-name-map';
+import packageJson from './package.json' with {type: 'json'};
+import {appendTagNameMap, createTagNameCollector} from './scripts/tag-name-map.ts';
 
 const root = fileURLToPath(new URL('.', import.meta.url));
 const fromRoot = (...parts: string[]) => resolve(root, ...parts);

protocol/languages/typescript/src/embedded_checkout_protocol.d.ts

@@ -1,56 +1,11 @@
 import { Client as ClientClass } from './client';
 import type { DecodedMessage, JSONRPCID } from './codec';
-import { type Delegation as DelegationType } from './generated/ProtocolNotifications';
+import { Delegations, SPEC_VERSION, notificationDescriptors, requestDescriptors, type Delegation as DelegationType } from './generated/ProtocolNotifications';
 import { url, type ProtocolURLOptions } from './url';
 export declare const EmbeddedCheckoutProtocol: {
-    readonly specVersion: "2026-08-25";
-    readonly Delegations: {
-        readonly paymentInstrumentsChange: "payment.instruments_change";
-        readonly paymentCredential: "payment.credential";
-        readonly fulfillmentAddressChange: "fulfillment.address_change";
-        readonly windowOpen: "window.open";
-    };
-    readonly Event: {
-        readonly ready: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.ready", import(".").ReadyRequest>, import(".").ReadyResult>;
-        readonly auth: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.auth", import(".").AuthRequest>, import(".").AuthResult>;
-        readonly paymentInstrumentsChange: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.payment.instruments_change_request", {
-            checkout: import(".").Checkout;
-        }>, import(".").InstrumentsChangeResult>;
-        readonly paymentCredential: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.payment.credential_request", {
-            checkout: import(".").Checkout;
-        }>, import(".").CredentialResult>;
-        readonly windowOpen: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.window.open_request", import(".").WindowOpenRequest>, import(".").WindowOpenResult>;
-        readonly fulfillmentAddressChange: import("./descriptors").RequestDescriptor<import("./descriptors").RequestMessage<"ec.fulfillment.address_change_request", {
-            checkout: import(".").Checkout;
-        }>, import(".").AddressChangeResult>;
-        readonly error: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.error", {
-            error: import(".").ErrorResponse;
-        }>>;
-        readonly start: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.start", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly complete: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.complete", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly messagesChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.messages.change", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly lineItemsChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.line_items.change", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly buyerChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.buyer.change", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly totalsChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.totals.change", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly paymentChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.payment.change", {
-            checkout: import(".").Checkout;
-        }>>;
-        readonly fulfillmentChange: import("./descriptors").NotificationDescriptor<import("./descriptors").NotificationMessage<"ec.fulfillment.change", {
-            checkout: import(".").Checkout;
-        }>>;
-    };
+    readonly specVersion: typeof SPEC_VERSION;
+    readonly Delegations: typeof Delegations;
+    readonly Event: typeof notificationDescriptors & typeof requestDescriptors;
     readonly url: typeof url;
     readonly Client: typeof ClientClass;
 };

protocol/languages/typescript/src/embedded_checkout_protocol.ts

@@ -9,13 +9,21 @@ import {
 } from './generated/ProtocolNotifications';
 import {url, type ProtocolURLOptions} from './url';
 
-export const EmbeddedCheckoutProtocol = {
+// Explicit type so the declaration can be emitted in isolation
+// (--isolatedDeclarations); `typeof` queries keep it in step with the sources.
+export const EmbeddedCheckoutProtocol: {
+  readonly specVersion: typeof SPEC_VERSION;
+  readonly Delegations: typeof Delegations;
+  readonly Event: typeof notificationDescriptors & typeof requestDescriptors;
+  readonly url: typeof url;
+  readonly Client: typeof ClientClass;
+} = {
   specVersion: SPEC_VERSION,
   Delegations,
   Event: {...notificationDescriptors, ...requestDescriptors},
   url,
   Client: ClientClass,
-} as const;
+};
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace EmbeddedCheckoutProtocol {

protocol/languages/typescript/src/generated/ProtocolNotifications.d.ts

@@ -1,5 +1,4 @@
 import { type NotificationDescriptor, type NotificationMessage, type RequestDescriptor, type RequestMessage } from '../descriptors';
-import { decodeCheckout, decodeErrorResponse } from './ProtocolCodecs';
 type AddressChangeResult = import('./Models').AddressChangeResult;
 type AuthRequest = import('./Models').AuthRequest;
 type AuthResult = import('./Models').AuthResult;
@@ -75,46 +74,14 @@ export type CheckoutProtocolNotificationMessage = {
     [K in keyof CheckoutProtocolCatalogParams]: NotificationMessage<K, CheckoutProtocolCatalogParams[K]>;
 }[keyof CheckoutProtocolCatalogParams];
 export type CheckoutProtocolCatalogPayloadDecoder<K extends keyof CheckoutProtocolCatalogPayloads> = (payload: unknown) => CheckoutProtocolCatalogPayloads[K];
-export declare const checkoutProtocolCatalogPayloadDecoders: {
-    "ec.error": typeof decodeErrorResponse;
-    "ec.start": typeof decodeCheckout;
-    "ec.complete": typeof decodeCheckout;
-    "ec.messages.change": typeof decodeCheckout;
-    "ec.line_items.change": typeof decodeCheckout;
-    "ec.buyer.change": typeof decodeCheckout;
-    "ec.totals.change": typeof decodeCheckout;
-    "ec.payment.change": typeof decodeCheckout;
-    "ec.fulfillment.change": typeof decodeCheckout;
+export type CheckoutProtocolCatalogPayloadDecoders = {
+    [K in keyof CheckoutProtocolCatalogPayloads]: CheckoutProtocolCatalogPayloadDecoder<K>;
 };
-export declare const notificationDescriptors: {
-    error: NotificationDescriptor<NotificationMessage<"ec.error", {
-        error: import("./Models").ErrorResponse;
-    }>>;
-    start: NotificationDescriptor<NotificationMessage<"ec.start", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    complete: NotificationDescriptor<NotificationMessage<"ec.complete", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    messagesChange: NotificationDescriptor<NotificationMessage<"ec.messages.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    lineItemsChange: NotificationDescriptor<NotificationMessage<"ec.line_items.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    buyerChange: NotificationDescriptor<NotificationMessage<"ec.buyer.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    totalsChange: NotificationDescriptor<NotificationMessage<"ec.totals.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    paymentChange: NotificationDescriptor<NotificationMessage<"ec.payment.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
-    fulfillmentChange: NotificationDescriptor<NotificationMessage<"ec.fulfillment.change", {
-        checkout: import("./Models").Checkout;
-    }>>;
+export declare const checkoutProtocolCatalogPayloadDecoders: CheckoutProtocolCatalogPayloadDecoders;
+export type NotificationDescriptors = {
+    [K in keyof typeof checkoutProtocolCatalog]: NotificationDescriptor<NotificationMessage<(typeof checkoutProtocolCatalog)[K], CheckoutProtocolCatalogParams[(typeof checkoutProtocolCatalog)[K]]>>;
 };
+export declare const notificationDescriptors: NotificationDescriptors;
 export declare const checkoutProtocolRequestCatalog: {
     readonly ready: "ec.ready";
     readonly auth: "ec.auth";
@@ -157,19 +124,9 @@ export interface CheckoutProtocolRequestParams {
 export type CheckoutProtocolRequestMessage = {
     [K in keyof CheckoutProtocolRequestParams]: RequestMessage<K, CheckoutProtocolRequestParams[K]>;
 }[keyof CheckoutProtocolRequestParams];
-export declare const requestDescriptors: {
-    ready: RequestDescriptor<RequestMessage<"ec.ready", import("./Models").ReadyRequest>, import("./Models").ReadyResult>;
-    auth: RequestDescriptor<RequestMessage<"ec.auth", import("./Models").AuthRequest>, import("./Models").AuthResult>;
-    paymentInstrumentsChange: RequestDescriptor<RequestMessage<"ec.payment.instruments_change_request", {
-        checkout: import("./Models").Checkout;
-    }>, import("./Models").InstrumentsChangeResult>;
-    paymentCredential: RequestDescriptor<RequestMessage<"ec.payment.credential_request", {
-        checkout: import("./Models").Checkout;
-    }>, import("./Models").CredentialResult>;
-    windowOpen: RequestDescriptor<RequestMessage<"ec.window.open_request", import("./Models").WindowOpenRequest>, import("./Models").WindowOpenResult>;
-    fulfillmentAddressChange: RequestDescriptor<RequestMessage<"ec.fulfillment.address_change_request", {
-        checkout: import("./Models").Checkout;
-    }>, import("./Models").AddressChangeResult>;
+export type RequestDescriptors = {
+    [K in keyof typeof checkoutProtocolRequestCatalog]: RequestDescriptor<RequestMessage<(typeof checkoutProtocolRequestCatalog)[K], CheckoutProtocolRequestParams[(typeof checkoutProtocolRequestCatalog)[K]]>, CheckoutProtocolRequestResults[(typeof checkoutProtocolRequestCatalog)[K]]>;
 };
+export declare const requestDescriptors: RequestDescriptors;
 export declare const embeddedCheckoutMethods: ReadonlySet<string>;
 export {};

protocol/languages/typescript/src/generated/ProtocolNotifications.ts

@@ -79,7 +79,12 @@ export type CheckoutProtocolCatalogPayloadDecoder<
   K extends keyof CheckoutProtocolCatalogPayloads,
 > = (payload: unknown) => CheckoutProtocolCatalogPayloads[K];
 
-export const checkoutProtocolCatalogPayloadDecoders = {
+export type CheckoutProtocolCatalogPayloadDecoders = {
+  [K in keyof CheckoutProtocolCatalogPayloads]:
+    CheckoutProtocolCatalogPayloadDecoder<K>;
+};
+
+export const checkoutProtocolCatalogPayloadDecoders: CheckoutProtocolCatalogPayloadDecoders = {
   [checkoutProtocolCatalog.error]: decodeErrorResponse,
   [checkoutProtocolCatalog.start]: decodeCheckout,
   [checkoutProtocolCatalog.complete]: decodeCheckout,
@@ -89,12 +94,18 @@ export const checkoutProtocolCatalogPayloadDecoders = {
   [checkoutProtocolCatalog.totalsChange]: decodeCheckout,
   [checkoutProtocolCatalog.paymentChange]: decodeCheckout,
   [checkoutProtocolCatalog.fulfillmentChange]: decodeCheckout,
-} satisfies {
-  [K in keyof CheckoutProtocolCatalogPayloads]:
-    CheckoutProtocolCatalogPayloadDecoder<K>;
 };
 
-export const notificationDescriptors = {
+export type NotificationDescriptors = {
+  [K in keyof typeof checkoutProtocolCatalog]: NotificationDescriptor<
+    NotificationMessage<
+      (typeof checkoutProtocolCatalog)[K],
+      CheckoutProtocolCatalogParams[(typeof checkoutProtocolCatalog)[K]]
+    >
+  >;
+};
+
+export const notificationDescriptors: NotificationDescriptors = {
   error: notificationDescriptor(
     checkoutProtocolCatalog.error,
     params => ({error: decodeErrorResponse((params as {error: unknown}).error)}),
@@ -131,13 +142,6 @@ export const notificationDescriptors = {
     checkoutProtocolCatalog.fulfillmentChange,
     params => ({checkout: decodeCheckout((params as {checkout: unknown}).checkout)}),
   ),
-} satisfies {
-  [K in keyof typeof checkoutProtocolCatalog]: NotificationDescriptor<
-    NotificationMessage<
-      (typeof checkoutProtocolCatalog)[K],
-      CheckoutProtocolCatalogParams[(typeof checkoutProtocolCatalog)[K]]
-    >
-  >;
 };
 
 export const checkoutProtocolRequestCatalog = {
@@ -186,7 +190,17 @@ export type CheckoutProtocolRequestMessage = {
   >;
 }[keyof CheckoutProtocolRequestParams];
 
-export const requestDescriptors = {
+export type RequestDescriptors = {
+  [K in keyof typeof checkoutProtocolRequestCatalog]: RequestDescriptor<
+    RequestMessage<
+      (typeof checkoutProtocolRequestCatalog)[K],
+      CheckoutProtocolRequestParams[(typeof checkoutProtocolRequestCatalog)[K]]
+    >,
+    CheckoutProtocolRequestResults[(typeof checkoutProtocolRequestCatalog)[K]]
+  >;
+};
+
+export const requestDescriptors: RequestDescriptors = {
   ready: requestDescriptor(
     checkoutProtocolRequestCatalog.ready,
     null,
@@ -223,14 +237,6 @@ export const requestDescriptors = {
     params => ({checkout: decodeCheckout((params as {checkout: unknown}).checkout)}),
     (result: AddressChangeResult) => encodeAddressChangeResult(result),
   ),
-} satisfies {
-  [K in keyof typeof checkoutProtocolRequestCatalog]: RequestDescriptor<
-    RequestMessage<
-      (typeof checkoutProtocolRequestCatalog)[K],
-      CheckoutProtocolRequestParams[(typeof checkoutProtocolRequestCatalog)[K]]
-    >,
-    CheckoutProtocolRequestResults[(typeof checkoutProtocolRequestCatalog)[K]]
-  >;
 };
 
 export const embeddedCheckoutMethods: ReadonlySet<string> = new Set([

protocol/languages/typescript/tsconfig.json

@@ -3,7 +3,9 @@
     "allowUnreachableCode": false,
     "allowUnusedLabels": false,
     "esModuleInterop": true,
+    "declaration": true,
     "forceConsistentCasingInFileNames": true,
+    "isolatedDeclarations": true,
     "lib": [
       "esnext"
     ],

protocol/scripts/generate_models.mjs

@@ -1112,6 +1112,7 @@ async function generateTypescript(specDir, output, {mapModelNames}) {
   await run("node", [
     tscBin,
     "--declaration",
+    "--isolatedDeclarations",
     "--emitDeclarationOnly",
     "--noEmit",
     "false",

protocol/scripts/generate_typescript_notifications.mjs

@@ -203,19 +203,30 @@ export type CheckoutProtocolCatalogPayloadDecoder<
   K extends keyof CheckoutProtocolCatalogPayloads,
 > = (payload: unknown) => CheckoutProtocolCatalogPayloads[K];
 
-export const checkoutProtocolCatalogPayloadDecoders = {
+export type CheckoutProtocolCatalogPayloadDecoders = {
+  [K in keyof CheckoutProtocolCatalogPayloads]:
+    CheckoutProtocolCatalogPayloadDecoder<K>;
+};
+
+export const checkoutProtocolCatalogPayloadDecoders: CheckoutProtocolCatalogPayloadDecoders = {
 ${notifications
   .map(
     notification =>
       `  [checkoutProtocolCatalog.${notification.identifier}]: decode${notification.typeName},`,
   )
   .join('\n')}
-} satisfies {
-  [K in keyof CheckoutProtocolCatalogPayloads]:
-    CheckoutProtocolCatalogPayloadDecoder<K>;
 };
 
-export const notificationDescriptors = {
+export type NotificationDescriptors = {
+  [K in keyof typeof checkoutProtocolCatalog]: NotificationDescriptor<
+    NotificationMessage<
+      (typeof checkoutProtocolCatalog)[K],
+      CheckoutProtocolCatalogParams[(typeof checkoutProtocolCatalog)[K]]
+    >
+  >;
+};
+
+export const notificationDescriptors: NotificationDescriptors = {
 ${notifications
   .map(
     notification =>
@@ -225,13 +236,6 @@ ${notifications
   ),`,
   )
   .join('\n')}
-} satisfies {
-  [K in keyof typeof checkoutProtocolCatalog]: NotificationDescriptor<
-    NotificationMessage<
-      (typeof checkoutProtocolCatalog)[K],
-      CheckoutProtocolCatalogParams[(typeof checkoutProtocolCatalog)[K]]
-    >
-  >;
 };
 
 export const checkoutProtocolRequestCatalog = {
@@ -260,7 +264,17 @@ export type CheckoutProtocolRequestMessage = {
   >;
 }[keyof CheckoutProtocolRequestParams];
 
-export const requestDescriptors = {
+export type RequestDescriptors = {
+  [K in keyof typeof checkoutProtocolRequestCatalog]: RequestDescriptor<
+    RequestMessage<
+      (typeof checkoutProtocolRequestCatalog)[K],
+      CheckoutProtocolRequestParams[(typeof checkoutProtocolRequestCatalog)[K]]
+    >,
+    CheckoutProtocolRequestResults[(typeof checkoutProtocolRequestCatalog)[K]]
+  >;
+};
+
+export const requestDescriptors: RequestDescriptors = {
 ${requests
   .map(
     request =>
@@ -272,14 +286,6 @@ ${requests
   ),`,
   )
   .join('\n')}
-} satisfies {
-  [K in keyof typeof checkoutProtocolRequestCatalog]: RequestDescriptor<
-    RequestMessage<
-      (typeof checkoutProtocolRequestCatalog)[K],
-      CheckoutProtocolRequestParams[(typeof checkoutProtocolRequestCatalog)[K]]
-    >,
-    CheckoutProtocolRequestResults[(typeof checkoutProtocolRequestCatalog)[K]]
-  >;
 };
 
 export const embeddedCheckoutMethods: ReadonlySet<string> = new Set([