@hartl-services/medusa-contracts 1.6.0 → 1.8.0

package/README.md

@@ -77,7 +77,12 @@ The order assistant (`order-assistant`) is not a JSON REST route: `paths` holds
 the MCP endpoint (`/mcp`), `schemas` the input and output schemas of its four
 tools, the tool names and the order metadata keys the assistant writes, and
 `types` their inferred types. A storefront never calls it; the consumer is an
-MCP client (an AI chatbot) and the base's own tests.
+MCP client (an AI chatbot) and the base's own tests. Since 1.7.0 the same
+subpaths also hold the assistant's OAuth sign-in: `paths.oauth` (discovery,
+registration, authorization, token), `paths.admin` and `paths.adminPages`
+(consent page and connected chatbots in the Admin), the request and response
+schemas of those endpoints, `ORDER_ASSISTANT_FEATURES` and
+`ORDER_ASSISTANT_OAUTH` (scope and lifetimes).
 
 File Gateway responses are binary and have no JSON response DTO. Public paths
 come from `paths/files`. Private gateway URLs are opaque, signed server results

package/dist/email/schemas.d.ts

@@ -15,6 +15,7 @@ export declare const EmailKindSchema: z.ZodEnum<{
     "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
     "user.invite": "user.invite";
     "system.credential_expiry.admin": "system.credential_expiry.admin";
+    "order.picked_up": "order.picked_up";
 }>;
 export declare const EmailMessageStatusSchema: z.ZodEnum<{
     unknown: "unknown";
@@ -61,7 +62,7 @@ export declare const EMAIL_ATTACHMENT_MAX_PDF_BYTES: number;
  * Customer mails an Admin can attach library documents (terms, legal notices,
  * flyers) to. Account, Shop and affiliate mails never carry them.
  */
-export declare const EMAIL_ATTACHABLE_KINDS: readonly ["order.received", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded"];
+export declare const EMAIL_ATTACHABLE_KINDS: readonly ["order.received", "order.shipped", "order.picked_up", "order.canceled", "order.return_requested", "order.return_received", "order.refunded"];
 export declare const EmailAttachableKindSchema: z.ZodEnum<{
     "order.received": "order.received";
     "order.shipped": "order.shipped";
@@ -69,6 +70,7 @@ export declare const EmailAttachableKindSchema: z.ZodEnum<{
     "order.return_requested": "order.return_requested";
     "order.return_received": "order.return_received";
     "order.refunded": "order.refunded";
+    "order.picked_up": "order.picked_up";
 }>;
 export declare const ListAdminEmailMessagesQuerySchema: z.ZodObject<{
     kind: z.ZodOptional<z.ZodEnum<{
@@ -87,6 +89,7 @@ export declare const ListAdminEmailMessagesQuerySchema: z.ZodObject<{
         "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
         "user.invite": "user.invite";
         "system.credential_expiry.admin": "system.credential_expiry.admin";
+        "order.picked_up": "order.picked_up";
     }>>;
     status: z.ZodOptional<z.ZodEnum<{
         unknown: "unknown";
@@ -117,7 +120,8 @@ export declare const CreateAdminEmailAttachmentDocumentSchema: z.ZodObject<{
         "order.return_requested": "order.return_requested";
         "order.return_received": "order.return_received";
         "order.refunded": "order.refunded";
-    }>>, z.ZodTransform<("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded")[], ("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded")[]>>;
+        "order.picked_up": "order.picked_up";
+    }>>, z.ZodTransform<("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded" | "order.picked_up")[], ("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded" | "order.picked_up")[]>>;
 }, z.core.$strict>;
 export declare const UpdateAdminEmailAttachmentDocumentSchema: z.ZodObject<{
     name: z.ZodString;
@@ -128,7 +132,8 @@ export declare const UpdateAdminEmailAttachmentDocumentSchema: z.ZodObject<{
         "order.return_requested": "order.return_requested";
         "order.return_received": "order.return_received";
         "order.refunded": "order.refunded";
-    }>>, z.ZodTransform<("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded")[], ("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded")[]>>>;
+        "order.picked_up": "order.picked_up";
+    }>>, z.ZodTransform<("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded" | "order.picked_up")[], ("order.received" | "order.shipped" | "order.canceled" | "order.return_requested" | "order.return_received" | "order.refunded" | "order.picked_up")[]>>>;
 }, z.core.$strict>;
 export declare const CreateAdminEmailAttachmentVersionSchema: z.ZodObject<{
     request_id: z.ZodString;
@@ -154,6 +159,7 @@ export declare const AdminEmailMessageSchema: z.ZodObject<{
         "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
         "user.invite": "user.invite";
         "system.credential_expiry.admin": "system.credential_expiry.admin";
+        "order.picked_up": "order.picked_up";
     }>;
     status: z.ZodEnum<{
         unknown: "unknown";
@@ -258,6 +264,7 @@ export declare const AdminEmailAttachmentDocumentSchema: z.ZodObject<{
         "order.return_requested": "order.return_requested";
         "order.return_received": "order.return_received";
         "order.refunded": "order.refunded";
+        "order.picked_up": "order.picked_up";
     }>>;
     versions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -289,6 +296,7 @@ export declare const ListAdminEmailMessagesResponseSchema: z.ZodObject<{
             "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
             "user.invite": "user.invite";
             "system.credential_expiry.admin": "system.credential_expiry.admin";
+            "order.picked_up": "order.picked_up";
         }>;
         status: z.ZodEnum<{
             unknown: "unknown";
@@ -360,6 +368,7 @@ export declare const GetAdminEmailMessageResponseSchema: z.ZodObject<{
             "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
             "user.invite": "user.invite";
             "system.credential_expiry.admin": "system.credential_expiry.admin";
+            "order.picked_up": "order.picked_up";
         }>;
         status: z.ZodEnum<{
             unknown: "unknown";
@@ -466,6 +475,7 @@ export declare const ResendAdminEmailMessageResponseSchema: z.ZodObject<{
             "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
             "user.invite": "user.invite";
             "system.credential_expiry.admin": "system.credential_expiry.admin";
+            "order.picked_up": "order.picked_up";
         }>;
         status: z.ZodEnum<{
             unknown: "unknown";
@@ -526,6 +536,7 @@ export declare const ListAdminEmailAttachmentDocumentsResponseSchema: z.ZodObjec
             "order.return_requested": "order.return_requested";
             "order.return_received": "order.return_received";
             "order.refunded": "order.refunded";
+            "order.picked_up": "order.picked_up";
         }>>;
         versions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -551,6 +562,7 @@ export declare const AdminEmailAttachmentDocumentResponseSchema: z.ZodObject<{
             "order.return_requested": "order.return_requested";
             "order.return_received": "order.return_received";
             "order.refunded": "order.refunded";
+            "order.picked_up": "order.picked_up";
         }>>;
         versions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -590,7 +602,7 @@ export declare const AdminDraftOrderConfirmationResponseSchema: z.ZodObject<{
  * Mails whose content an Admin edits as a block template. Every other kind
  * keeps its code template.
  */
-export declare const EMAIL_EDITABLE_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "auth.admin_password_reset", "auth.verification", "auth.login_code", "user.invite", "affiliate.consignment_report_due", "affiliate.application_submitted.admin"];
+export declare const EMAIL_EDITABLE_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.picked_up", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "auth.admin_password_reset", "auth.verification", "auth.login_code", "user.invite", "affiliate.consignment_report_due", "affiliate.application_submitted.admin"];
 export declare const EmailEditableKindSchema: z.ZodEnum<{
     "order.received": "order.received";
     "order.received.admin": "order.received.admin";
@@ -606,6 +618,7 @@ export declare const EmailEditableKindSchema: z.ZodEnum<{
     "affiliate.consignment_report_due": "affiliate.consignment_report_due";
     "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
     "user.invite": "user.invite";
+    "order.picked_up": "order.picked_up";
 }>;
 /** Server-rendered blocks with the mail's real data. */
 export declare const EmailTemplateDynamicBlockSchema: z.ZodEnum<{
@@ -658,6 +671,12 @@ export declare const EMAIL_TEMPLATE_CATALOG: {
         readonly placeholders: readonly ["shop_name", "order_number", "customer_name"];
         readonly required_blocks: readonly [];
     };
+    readonly "order.picked_up": {
+        readonly blocks: readonly ["details", "item_list"];
+        readonly conditions: readonly ["invoice_attached"];
+        readonly placeholders: readonly ["shop_name", "order_number", "customer_name"];
+        readonly required_blocks: readonly [];
+    };
     readonly "order.canceled": {
         readonly blocks: readonly ["details", "order_summary"];
         readonly conditions: readonly ["cancellation_attached"];
@@ -1798,6 +1817,7 @@ export declare const AdminEmailTemplateSummarySchema: z.ZodObject<{
         "affiliate.consignment_report_due": "affiliate.consignment_report_due";
         "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
         "user.invite": "user.invite";
+        "order.picked_up": "order.picked_up";
     }>;
     customized: z.ZodBoolean;
     code_override: z.ZodBoolean;
@@ -1820,6 +1840,7 @@ export declare const ListAdminEmailTemplatesResponseSchema: z.ZodObject<{
             "affiliate.consignment_report_due": "affiliate.consignment_report_due";
             "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
             "user.invite": "user.invite";
+            "order.picked_up": "order.picked_up";
         }>;
         customized: z.ZodBoolean;
         code_override: z.ZodBoolean;
@@ -1843,6 +1864,7 @@ export declare const AdminEmailTemplateResponseSchema: z.ZodObject<{
             "affiliate.consignment_report_due": "affiliate.consignment_report_due";
             "affiliate.application_submitted.admin": "affiliate.application_submitted.admin";
             "user.invite": "user.invite";
+            "order.picked_up": "order.picked_up";
         }>;
         customized: z.ZodBoolean;
         code_override: z.ZodBoolean;
@@ -2400,6 +2422,7 @@ export declare const SetAdminEmailAttachmentMailKindSchema: z.ZodObject<{
         "order.return_requested": "order.return_requested";
         "order.return_received": "order.return_received";
         "order.refunded": "order.refunded";
+        "order.picked_up": "order.picked_up";
     }>;
     attached: z.ZodBoolean;
 }, z.core.$strict>;

package/dist/email/schemas.js

@@ -19,6 +19,7 @@ exports.EmailKindSchema = zod_1.z.enum([
     "affiliate.application_submitted.admin",
     "user.invite",
     "system.credential_expiry.admin",
+    "order.picked_up",
 ]);
 exports.EmailMessageStatusSchema = zod_1.z.enum([
     "pending",
@@ -73,6 +74,7 @@ const NullableWireDateSchema = primitives_1.WireDateSchema.nullable();
 exports.EMAIL_ATTACHABLE_KINDS = [
     "order.received",
     "order.shipped",
+    "order.picked_up",
     "order.canceled",
     "order.return_requested",
     "order.return_received",
@@ -257,6 +259,7 @@ exports.EMAIL_EDITABLE_KINDS = [
     "order.received",
     "order.received.admin",
     "order.shipped",
+    "order.picked_up",
     "order.canceled",
     "order.return_requested",
     "order.return_received",
@@ -326,6 +329,12 @@ exports.EMAIL_TEMPLATE_CATALOG = {
         placeholders: ["shop_name", "order_number", "customer_name"],
         required_blocks: [],
     },
+    "order.picked_up": {
+        blocks: ["details", "item_list"],
+        conditions: ["invoice_attached"],
+        placeholders: ["shop_name", "order_number", "customer_name"],
+        required_blocks: [],
+    },
     "order.canceled": {
         blocks: ["details", "order_summary"],
         conditions: ["cancellation_attached"],

package/dist/esm/email/schemas.mjs

@@ -16,6 +16,7 @@ export const EmailKindSchema = z.enum([
     "affiliate.application_submitted.admin",
     "user.invite",
     "system.credential_expiry.admin",
+    "order.picked_up",
 ]);
 export const EmailMessageStatusSchema = z.enum([
     "pending",
@@ -70,6 +71,7 @@ const NullableWireDateSchema = WireDateSchema.nullable();
 export const EMAIL_ATTACHABLE_KINDS = [
     "order.received",
     "order.shipped",
+    "order.picked_up",
     "order.canceled",
     "order.return_requested",
     "order.return_received",
@@ -254,6 +256,7 @@ export const EMAIL_EDITABLE_KINDS = [
     "order.received",
     "order.received.admin",
     "order.shipped",
+    "order.picked_up",
     "order.canceled",
     "order.return_requested",
     "order.return_received",
@@ -323,6 +326,12 @@ export const EMAIL_TEMPLATE_CATALOG = {
         placeholders: ["shop_name", "order_number", "customer_name"],
         required_blocks: [],
     },
+    "order.picked_up": {
+        blocks: ["details", "item_list"],
+        conditions: ["invoice_attached"],
+        placeholders: ["shop_name", "order_number", "customer_name"],
+        required_blocks: [],
+    },
     "order.canceled": {
         blocks: ["details", "order_summary"],
         conditions: ["cancellation_attached"],

package/dist/esm/order-assistant/paths.mjs

@@ -1,7 +1,33 @@
 /**
  * The shop's MCP endpoint for the order assistant (Streamable HTTP,
  * stateless). Outside `/admin` and `/store`: it authenticates on its own.
+ *
+ * `oauth`: the OAuth 2.1 endpoints an MCP client (claude.ai, ChatGPT) uses
+ * to sign an Admin user in; the well-known paths are fixed by RFC 9728 and
+ * RFC 8414. `admin`: the Admin API behind the consent page and the list of
+ * connected chatbots. `adminPages`: Admin pages, relative to the Admin root.
  */
 export const orderAssistantPaths = {
     mcp: "/mcp",
+    oauth: {
+        protectedResourceMetadata: "/.well-known/oauth-protected-resource",
+        /** Same document; clients probe the path of the MCP endpoint first. */
+        protectedResourceMetadataForMcp: "/.well-known/oauth-protected-resource/mcp",
+        authorizationServerMetadata: "/.well-known/oauth-authorization-server",
+        register: "/mcp/oauth/register",
+        authorize: "/mcp/oauth/authorize",
+        token: "/mcp/oauth/token",
+    },
+    admin: {
+        authorization: (authorizationId) => `/admin/order-assistant/authorizations/${encodeURIComponent(authorizationId)}`,
+        connections: "/admin/order-assistant/connections",
+        connection: (connectionId) => `/admin/order-assistant/connections/${encodeURIComponent(connectionId)}`,
+    },
+    adminPages: {
+        /**
+         * The request id is a path segment on purpose: the Admin login returns
+         * to the path it came from and drops the query string.
+         */
+        authorize: (authorizationId) => `/order-assistant/authorize/${encodeURIComponent(authorizationId)}`,
+    },
 };

package/dist/esm/order-assistant/schemas.mjs

@@ -1,5 +1,5 @@
 import { z } from "@medusajs/framework/zod";
-import { NonEmptyStringSchema } from "../shared/primitives.mjs";
+import { NonEmptyStringSchema, WireDateSchema } from "../shared/primitives.mjs";
 /** Plugin key and container key of the order assistant in the base. */
 export const ORDER_ASSISTANT_PLUGIN_KEY = "order_assistant";
 /** Tool names as the MCP client sees them. */
@@ -181,3 +181,205 @@ export const CreateDraftOrderOutputSchema = z.object({
     /** Path of the draft in the Admin, relative to the backend URL. */
     admin_path: z.string(),
 });
+// --- Anmeldung per OAuth (MCP authorization, OAuth 2.1) --------------------
+/** Feature keys of the order assistant's plugin toggles. */
+export const ORDER_ASSISTANT_FEATURES = {
+    oauth: "oauth",
+};
+export const ORDER_ASSISTANT_OAUTH = {
+    /** The one scope: use the assistant's tools as the signed-in Admin user. */
+    scope: "order_assistant",
+    accessTokenTtlSeconds: 3600,
+    /** A connection ends when its refresh token stays unused this long. */
+    connectionIdleDays: 30,
+    /** How long the consent page may stay open. */
+    authorizationRequestTtlSeconds: 600,
+    /** How long the client has to redeem the code after the consent. */
+    authorizationCodeTtlSeconds: 120,
+    maxRedirectUris: 10,
+    maxUriLength: 2000,
+    maxClientNameLength: 120,
+    maxStateLength: 2000,
+};
+const OAUTH_LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** `http://localhost`, `http://127.0.0.1` or `http://[::1]`, any port. */
+export const isOAuthLoopbackRedirectUri = (value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "http:" && OAUTH_LOOPBACK_HOSTS.includes(url.hostname));
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * A redirect URI a client may register: https, or http on a loopback address
+ * (native clients such as Claude Code), without credentials or fragment.
+ */
+export const OAuthRedirectUriSchema = z
+    .string()
+    .max(ORDER_ASSISTANT_OAUTH.maxUriLength)
+    .refine((value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.hash || url.username || url.password) {
+        return false;
+    }
+    return url.protocol === "https:" || isOAuthLoopbackRedirectUri(value);
+}, {
+    message: "A redirect URI must use https, or http on a loopback address, and carry no fragment.",
+});
+/**
+ * Dynamic client registration request (RFC 7591). Unknown metadata is
+ * ignored; the requested authentication method, grant and response types are
+ * accepted as sent and answered with what the server actually supports.
+ */
+export const OAuthClientRegistrationRequestSchema = z.object({
+    redirect_uris: z
+        .array(OAuthRedirectUriSchema)
+        .min(1)
+        .max(ORDER_ASSISTANT_OAUTH.maxRedirectUris),
+    client_name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(ORDER_ASSISTANT_OAUTH.maxClientNameLength)
+        .optional(),
+});
+export const OAuthClientRegistrationResponseSchema = z.object({
+    client_id: z.string(),
+    /** Seconds since the epoch. */
+    client_id_issued_at: z.number(),
+    client_name: z.string().optional(),
+    redirect_uris: z.array(z.string()),
+    /** Public clients only: PKCE instead of a client secret. */
+    token_endpoint_auth_method: z.literal("none"),
+    grant_types: z.array(z.string()),
+    response_types: z.array(z.string()),
+    scope: z.string(),
+});
+/** Query of the authorization endpoint, before the client is looked up. */
+export const OAuthAuthorizeQuerySchema = z.object({
+    client_id: z.string().min(1).max(200),
+    redirect_uri: z.string().min(1).max(ORDER_ASSISTANT_OAUTH.maxUriLength),
+    response_type: z.string().max(100).optional(),
+    code_challenge: z.string().max(200).optional(),
+    code_challenge_method: z.string().max(20).optional(),
+    state: z.string().max(ORDER_ASSISTANT_OAUTH.maxStateLength).optional(),
+    scope: z.string().max(1000).optional(),
+    resource: z.string().max(ORDER_ASSISTANT_OAUTH.maxUriLength).optional(),
+});
+/** Body of the token endpoint (`application/x-www-form-urlencoded`). */
+export const OAuthTokenRequestSchema = z.discriminatedUnion("grant_type", [
+    z.object({
+        grant_type: z.literal("authorization_code"),
+        code: z.string().min(1).max(200),
+        /** RFC 7636: 43 to 128 unreserved characters. */
+        code_verifier: z.string().regex(/^[A-Za-z0-9\-._~]{43,128}$/),
+        client_id: z.string().min(1).max(200),
+        redirect_uri: z.string().max(ORDER_ASSISTANT_OAUTH.maxUriLength).optional(),
+        resource: z.string().max(ORDER_ASSISTANT_OAUTH.maxUriLength).optional(),
+    }),
+    z.object({
+        grant_type: z.literal("refresh_token"),
+        refresh_token: z.string().min(1).max(200),
+        client_id: z.string().min(1).max(200),
+        resource: z.string().max(ORDER_ASSISTANT_OAUTH.maxUriLength).optional(),
+    }),
+]);
+export const OAuthTokenResponseSchema = z.object({
+    access_token: z.string(),
+    token_type: z.literal("Bearer"),
+    /** Seconds until the access token expires. */
+    expires_in: z.number(),
+    /** Replaces the refresh token that was sent; the old one stops working. */
+    refresh_token: z.string(),
+    scope: z.string(),
+});
+export const OAuthErrorCodeSchema = z.enum([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "invalid_target",
+    "invalid_client_metadata",
+    "invalid_redirect_uri",
+    "unsupported_grant_type",
+    "unsupported_response_type",
+    "access_denied",
+    "temporarily_unavailable",
+]);
+/** Error body of the registration and token endpoints (RFC 6749, RFC 7591). */
+export const OAuthErrorResponseSchema = z.object({
+    error: OAuthErrorCodeSchema,
+    error_description: z.string(),
+});
+/** RFC 9728: where the MCP endpoint's authorization server is. */
+export const OAuthProtectedResourceMetadataSchema = z.object({
+    resource: z.string(),
+    authorization_servers: z.array(z.string()),
+    bearer_methods_supported: z.array(z.string()),
+    scopes_supported: z.array(z.string()),
+    resource_name: z.string(),
+});
+/** RFC 8414: the authorization server's endpoints and capabilities. */
+export const OAuthAuthorizationServerMetadataSchema = z.object({
+    issuer: z.string(),
+    authorization_endpoint: z.string(),
+    token_endpoint: z.string(),
+    registration_endpoint: z.string(),
+    response_types_supported: z.array(z.string()),
+    grant_types_supported: z.array(z.string()),
+    code_challenge_methods_supported: z.array(z.string()),
+    token_endpoint_auth_methods_supported: z.array(z.string()),
+    scopes_supported: z.array(z.string()),
+    /** RFC 9207: every authorization response carries `iss`. */
+    authorization_response_iss_parameter_supported: z.boolean(),
+});
+/** What the consent page shows about a pending sign-in request. */
+export const AdminOrderAssistantAuthorizationSchema = z.object({
+    id: z.string(),
+    /** Name the chatbot registered with; `null` when it gave none. */
+    client_name: z.string().nullable(),
+    /** Host the browser is sent back to after the decision. */
+    redirect_host: z.string(),
+    /** True when the chatbot runs on this computer (loopback redirect). */
+    redirect_is_loopback: z.boolean(),
+    /** True when the host belongs to a chatbot service the shop knows. */
+    redirect_is_known: z.boolean(),
+    expires_at: WireDateSchema,
+});
+export const AdminOrderAssistantAuthorizationResponseSchema = z.object({
+    authorization: AdminOrderAssistantAuthorizationSchema,
+});
+export const DecideOrderAssistantAuthorizationSchema = z
+    .object({ approve: z.boolean() })
+    .strict();
+export const DecideOrderAssistantAuthorizationResponseSchema = z.object({
+    /** Where the browser must go next: the chatbot's redirect URI. */
+    redirect_to: z.string(),
+});
+/** One chatbot an Admin user connected through OAuth. */
+export const AdminOrderAssistantConnectionSchema = z.object({
+    id: z.string(),
+    client_name: z.string().nullable(),
+    redirect_host: z.string(),
+    user_id: z.string(),
+    /** `null` when the Admin user no longer exists. */
+    user_email: z.string().nullable(),
+    created_at: WireDateSchema,
+    last_used_at: WireDateSchema.nullable(),
+    /** When the connection ends unless the chatbot uses it before. */
+    expires_at: WireDateSchema,
+});
+export const AdminOrderAssistantConnectionsResponseSchema = z.object({
+    connections: z.array(AdminOrderAssistantConnectionSchema),
+});
+export const DeleteOrderAssistantConnectionResponseSchema = z.object({
+    id: z.string(),
+    deleted: z.literal(true),
+});

package/dist/order-assistant/paths.d.ts

@@ -1,7 +1,33 @@
 /**
  * The shop's MCP endpoint for the order assistant (Streamable HTTP,
  * stateless). Outside `/admin` and `/store`: it authenticates on its own.
+ *
+ * `oauth`: the OAuth 2.1 endpoints an MCP client (claude.ai, ChatGPT) uses
+ * to sign an Admin user in; the well-known paths are fixed by RFC 9728 and
+ * RFC 8414. `admin`: the Admin API behind the consent page and the list of
+ * connected chatbots. `adminPages`: Admin pages, relative to the Admin root.
  */
 export declare const orderAssistantPaths: {
     readonly mcp: "/mcp";
+    readonly oauth: {
+        readonly protectedResourceMetadata: "/.well-known/oauth-protected-resource";
+        /** Same document; clients probe the path of the MCP endpoint first. */
+        readonly protectedResourceMetadataForMcp: "/.well-known/oauth-protected-resource/mcp";
+        readonly authorizationServerMetadata: "/.well-known/oauth-authorization-server";
+        readonly register: "/mcp/oauth/register";
+        readonly authorize: "/mcp/oauth/authorize";
+        readonly token: "/mcp/oauth/token";
+    };
+    readonly admin: {
+        readonly authorization: (authorizationId: string) => string;
+        readonly connections: "/admin/order-assistant/connections";
+        readonly connection: (connectionId: string) => string;
+    };
+    readonly adminPages: {
+        /**
+         * The request id is a path segment on purpose: the Admin login returns
+         * to the path it came from and drops the query string.
+         */
+        readonly authorize: (authorizationId: string) => string;
+    };
 };

package/dist/order-assistant/paths.js

@@ -4,7 +4,33 @@ exports.orderAssistantPaths = void 0;
 /**
  * The shop's MCP endpoint for the order assistant (Streamable HTTP,
  * stateless). Outside `/admin` and `/store`: it authenticates on its own.
+ *
+ * `oauth`: the OAuth 2.1 endpoints an MCP client (claude.ai, ChatGPT) uses
+ * to sign an Admin user in; the well-known paths are fixed by RFC 9728 and
+ * RFC 8414. `admin`: the Admin API behind the consent page and the list of
+ * connected chatbots. `adminPages`: Admin pages, relative to the Admin root.
  */
 exports.orderAssistantPaths = {
     mcp: "/mcp",
+    oauth: {
+        protectedResourceMetadata: "/.well-known/oauth-protected-resource",
+        /** Same document; clients probe the path of the MCP endpoint first. */
+        protectedResourceMetadataForMcp: "/.well-known/oauth-protected-resource/mcp",
+        authorizationServerMetadata: "/.well-known/oauth-authorization-server",
+        register: "/mcp/oauth/register",
+        authorize: "/mcp/oauth/authorize",
+        token: "/mcp/oauth/token",
+    },
+    admin: {
+        authorization: (authorizationId) => `/admin/order-assistant/authorizations/${encodeURIComponent(authorizationId)}`,
+        connections: "/admin/order-assistant/connections",
+        connection: (connectionId) => `/admin/order-assistant/connections/${encodeURIComponent(connectionId)}`,
+    },
+    adminPages: {
+        /**
+         * The request id is a path segment on purpose: the Admin login returns
+         * to the path it came from and drops the query string.
+         */
+        authorize: (authorizationId) => `/order-assistant/authorize/${encodeURIComponent(authorizationId)}`,
+    },
 };