@keystrokehq/shopify 0.0.1

package/README.md

@@ -0,0 +1,178 @@
+# @keystrokehq/shopify
+
+Shopify Admin API integration for Keystroke workflows.
+
+The package root is intentionally non-canonical. Import from explicit subpaths.
+
+## Public Subpaths
+
+- `@keystrokehq/shopify/connection`
+- `@keystrokehq/shopify/client`
+- `@keystrokehq/shopify/schemas`
+- `@keystrokehq/shopify/events`
+- `@keystrokehq/shopify/shop`
+- `@keystrokehq/shopify/products`
+- `@keystrokehq/shopify/collections`
+- `@keystrokehq/shopify/orders`
+- `@keystrokehq/shopify/customers`
+- `@keystrokehq/shopify/blogs`
+- `@keystrokehq/shopify/articles`
+- `@keystrokehq/shopify/locations`
+- `@keystrokehq/shopify/inventory`
+- `@keystrokehq/shopify/fulfillments`
+- `@keystrokehq/shopify/triggers`
+
+## Read Store Data
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+import { shopify } from '@keystrokehq/shopify/connection';
+import { getShop } from '@keystrokehq/shopify/shop';
+import { listProducts } from '@keystrokehq/shopify/products';
+
+export const syncCatalog = new Workflow({
+  id: 'sync-shopify-catalog',
+  name: 'Sync Shopify Catalog',
+  input: z.object({}),
+  output: z.object({
+    credentialSetId: z.string(),
+    storeName: z.string(),
+    productCount: z.number(),
+  }),
+  run: async () => {
+    const store = await getShop.run({});
+    const products = await listProducts.run({
+      first: 25,
+      query: 'status:active',
+    });
+
+    return {
+      credentialSetId: shopify.resolvedCredentialSetId,
+      storeName: store.name,
+      productCount: products.nodes.length,
+    };
+  },
+});
+```
+
+## Create Orders And Adjust Inventory
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+import { createOrder } from '@keystrokehq/shopify/orders';
+import { adjustInventoryQuantities } from '@keystrokehq/shopify/inventory';
+
+export const backofficeWriteFlow = new Workflow({
+  id: 'shopify-backoffice-write-flow',
+  name: 'Shopify Backoffice Write Flow',
+  input: z.object({ variantId: z.string(), inventoryItemId: z.string(), locationId: z.string() }),
+  output: z.object({ queued: z.boolean() }),
+  run: async (input) => {
+    await createOrder.run({
+      currency: 'USD',
+      email: 'buyer@example.com',
+      lineItems: [
+        {
+          variantId: input.variantId,
+          quantity: 1,
+        },
+      ],
+    });
+
+    await adjustInventoryQuantities.run({
+      reason: 'correction',
+      referenceDocumentUri: 'gid://keystroke/inventory-adjustment/docs-example',
+      changes: [
+        {
+          inventoryItemId: input.inventoryItemId,
+          locationId: input.locationId,
+          delta: -1,
+        },
+      ],
+    });
+
+    return { queued: true };
+  },
+});
+```
+
+## Bind Webhook Triggers
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+import { webhooks } from '@keystrokehq/shopify/triggers';
+
+const orderCreated = webhooks.orderCreated({
+  name: 'Shopify Order Created',
+  transform: (event) => ({
+    orderId: event.resourceId ?? event.payload.admin_graphql_api_id ?? '',
+    topic: event.topic,
+  }),
+});
+
+export const onNewShopifyOrder = new Workflow({
+  id: 'on-new-shopify-order',
+  name: 'On New Shopify Order',
+  input: z.object({
+    orderId: z.string(),
+    topic: z.literal('orders/create'),
+  }),
+  output: z.object({ ok: z.boolean() }),
+  triggers: [orderCreated],
+  run: async () => ({ ok: true }),
+});
+```
+
+## Notes
+
+- Mutating operations are marked with `needsApproval: true`.
+- Shopify webhook helpers are direct-binding surfaces under `@keystrokehq/shopify/triggers`.
+- Hidden `_official` and `_runtime` exports are for repo internals, not workflow authoring.
+
+## Live Test Runbook
+
+The Shopify package now has dedicated `test:int` coverage for every exported operation plus live webhook subscription management:
+
+- `shop.int.test.ts`
+- `products.int.test.ts`
+- `collections.int.test.ts`
+- `customers.int.test.ts`
+- `blogs.int.test.ts`
+- `articles.int.test.ts`
+- `orders.int.test.ts`
+- `inventory.int.test.ts`
+- `locations.int.test.ts`
+- `fulfillments.int.test.ts`
+- `webhook-management.int.test.ts`
+
+Set up `.env.test` with at least:
+
+- `RUN_LIVE_INT=true`
+- `SHOPIFY_LIVE_STORE_DOMAIN`
+- `SHOPIFY_LIVE_ACCESS_TOKEN`
+- `SHOPIFY_LIVE_REFRESH_TOKEN` for control-plane refresh coverage
+- `PUBLIC_SERVER_URL` for webhook subscription coverage
+- `KEYSTROKE_PLATFORM_SHOPIFY_APP_ID`
+- `KEYSTROKE_PLATFORM_SHOPIFY_CLIENT_ID`
+- `KEYSTROKE_PLATFORM_SHOPIFY_CLIENT_SECRET`
+- `KEYSTROKE_PLATFORM_SHOPIFY_WEBHOOK_SECRET`
+
+Recommended execution flow:
+
+```bash
+pnpm test:int:wiring
+pnpm --filter @keystrokehq/shopify test:int
+pnpm --filter @keystroke/server test:int
+pnpm --filter @keystroke/control-plane test:int
+```
+
+Operational guidance:
+
+- Use a dedicated disposable dev store. `orders`, `inventory`, `fulfillments`, and webhook tests are destructive by design.
+- Keep `PUBLIC_SERVER_URL` pointed at a real public tunnel or staging URL when exercising webhook subscription or OAuth callback flows.
+- The package test helpers try to clean up created products, collections, blogs, articles, and order-free customers automatically.
+- Orders with fulfillment history and customers with placed orders should be treated as disposable-store artifacts rather than shared-environment fixtures.
+- Shopify webhook subscription management requires `read_webhooks` and `write_webhooks` scopes in addition to the Admin API scopes used by the operation surface.

package/dist/_official/index.d.mts

@@ -0,0 +1,3 @@
+import { i as shopifyOfficialIntegration, n as shopify, r as shopifyBundle, t as ShopifyCredentials } from "../integration-BwDBsGX-.mjs";
+import { n as shopifyAppCredentialSet, r as shopifyPlatformProviderSeed, t as ShopifyAppCredentials } from "../provider-app-DHxVZI6q.mjs";
+export { type ShopifyAppCredentials, type ShopifyCredentials, shopify, shopifyAppCredentialSet, shopifyBundle, shopifyOfficialIntegration, shopifyPlatformProviderSeed };

package/dist/_official/index.mjs

@@ -0,0 +1,3 @@
+import { a as shopifyAppCredentialSet, n as shopifyBundle, o as shopifyPlatformProviderSeed, r as shopifyOfficialIntegration, t as shopify } from "../integration-BN3pjCz4.mjs";
+
+export { shopify, shopifyAppCredentialSet, shopifyBundle, shopifyOfficialIntegration, shopifyPlatformProviderSeed };

package/dist/_runtime/index.d.mts

@@ -0,0 +1,56 @@
+import { t as ShopifyCredentials } from "../integration-BwDBsGX-.mjs";
+import { z } from "zod";
+
+//#region src/webhook-management.d.ts
+declare const SHOPIFY_WEBHOOK_RUNTIME_DEFINITIONS: readonly [{
+  readonly eventTopic: "products/create";
+  readonly subscriptionTopic: "PRODUCTS_CREATE";
+  readonly path: "/shopify/products/create";
+}, {
+  readonly eventTopic: "products/update";
+  readonly subscriptionTopic: "PRODUCTS_UPDATE";
+  readonly path: "/shopify/products/update";
+}, {
+  readonly eventTopic: "products/delete";
+  readonly subscriptionTopic: "PRODUCTS_DELETE";
+  readonly path: "/shopify/products/delete";
+}, {
+  readonly eventTopic: "orders/create";
+  readonly subscriptionTopic: "ORDERS_CREATE";
+  readonly path: "/shopify/orders/create";
+}, {
+  readonly eventTopic: "orders/updated";
+  readonly subscriptionTopic: "ORDERS_UPDATED";
+  readonly path: "/shopify/orders/updated";
+}, {
+  readonly eventTopic: "orders/cancelled";
+  readonly subscriptionTopic: "ORDERS_CANCELLED";
+  readonly path: "/shopify/orders/cancelled";
+}, {
+  readonly eventTopic: "orders/fulfilled";
+  readonly subscriptionTopic: "ORDERS_FULFILLED";
+  readonly path: "/shopify/orders/fulfilled";
+}];
+declare const webhookSubscriptionSchema: z.ZodObject<{
+  id: z.ZodString;
+  topic: z.ZodEnum<{
+    PRODUCTS_CREATE: "PRODUCTS_CREATE";
+    PRODUCTS_UPDATE: "PRODUCTS_UPDATE";
+    PRODUCTS_DELETE: "PRODUCTS_DELETE";
+    ORDERS_CREATE: "ORDERS_CREATE";
+    ORDERS_UPDATED: "ORDERS_UPDATED";
+    ORDERS_CANCELLED: "ORDERS_CANCELLED";
+    ORDERS_FULFILLED: "ORDERS_FULFILLED";
+  }>;
+  uri: z.ZodString;
+}, z.core.$strip>;
+interface EnsureShopifyWebhookSubscriptionsResult {
+  readonly kept: readonly string[];
+  readonly created: readonly string[];
+  readonly deleted: readonly string[];
+}
+declare function buildShopifyWebhookCallbackUri(baseUrl: string, path: string): string;
+declare function listShopifyWebhookSubscriptions(credentials: ShopifyCredentials): Promise<readonly z.infer<typeof webhookSubscriptionSchema>[]>;
+declare function ensureShopifyWebhookSubscriptions(credentials: ShopifyCredentials, callbackBaseUrl: string): Promise<EnsureShopifyWebhookSubscriptionsResult>;
+//#endregion
+export { SHOPIFY_WEBHOOK_RUNTIME_DEFINITIONS, buildShopifyWebhookCallbackUri, ensureShopifyWebhookSubscriptions, listShopifyWebhookSubscriptions };

package/dist/_runtime/index.mjs

@@ -0,0 +1,3 @@
+import { i as listShopifyWebhookSubscriptions, n as buildShopifyWebhookCallbackUri, r as ensureShopifyWebhookSubscriptions, t as SHOPIFY_WEBHOOK_RUNTIME_DEFINITIONS } from "../webhook-management-BmIxO0vr.mjs";
+
+export { SHOPIFY_WEBHOOK_RUNTIME_DEFINITIONS, buildShopifyWebhookCallbackUri, ensureShopifyWebhookSubscriptions, listShopifyWebhookSubscriptions };

package/dist/articles.d.mts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import * as _keystrokehq_core0 from "@keystrokehq/core";
+import * as _keystrokehq_core_credential_set0 from "@keystrokehq/core/credential-set";
+
+//#region src/articles.d.ts
+declare const listArticles: _keystrokehq_core0.Operation<z.ZodObject<{
+  first: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  after: z.ZodOptional<z.ZodString>;
+  query: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  nodes: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    handle: z.ZodString;
+    blog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      id: z.ZodString;
+      title: z.ZodString;
+      handle: z.ZodString;
+      createdAt: z.ZodOptional<z.ZodISODateTime>;
+      updatedAt: z.ZodOptional<z.ZodISODateTime>;
+      commentPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+      templateSuffix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      url: z.ZodURL;
+      altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    publishedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    updatedAt: z.ZodOptional<z.ZodISODateTime>;
+  }, z.core.$strip>>;
+  pageInfo: z.ZodObject<{
+    hasNextPage: z.ZodBoolean;
+    hasPreviousPage: z.ZodOptional<z.ZodBoolean>;
+    startCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endCursor: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"shopify", z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const getArticle: _keystrokehq_core0.Operation<z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  handle: z.ZodString;
+  blog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    handle: z.ZodString;
+    createdAt: z.ZodOptional<z.ZodISODateTime>;
+    updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    commentPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    templateSuffix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    url: z.ZodURL;
+    altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  publishedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+  updatedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"shopify", z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const createArticle: _keystrokehq_core0.Operation<z.ZodObject<{
+  handle: z.ZodOptional<z.ZodString>;
+  body: z.ZodOptional<z.ZodString>;
+  summary: z.ZodOptional<z.ZodString>;
+  authorName: z.ZodOptional<z.ZodString>;
+  isPublished: z.ZodOptional<z.ZodBoolean>;
+  publishDate: z.ZodOptional<z.ZodISODateTime>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  blogId: z.ZodString;
+  title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  handle: z.ZodString;
+  blog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    handle: z.ZodString;
+    createdAt: z.ZodOptional<z.ZodISODateTime>;
+    updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    commentPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    templateSuffix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    url: z.ZodURL;
+    altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  publishedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+  updatedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"shopify", z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const updateArticle: _keystrokehq_core0.Operation<z.ZodObject<{
+  blogId: z.ZodOptional<z.ZodString>;
+  title: z.ZodOptional<z.ZodString>;
+  handle: z.ZodOptional<z.ZodString>;
+  body: z.ZodOptional<z.ZodString>;
+  summary: z.ZodOptional<z.ZodString>;
+  authorName: z.ZodOptional<z.ZodString>;
+  isPublished: z.ZodOptional<z.ZodBoolean>;
+  publishDate: z.ZodOptional<z.ZodISODateTime>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  id: z.ZodString;
+  redirectNewHandle: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  handle: z.ZodString;
+  blog: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    handle: z.ZodString;
+    createdAt: z.ZodOptional<z.ZodISODateTime>;
+    updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    commentPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    templateSuffix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    url: z.ZodURL;
+    altText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  publishedAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+  updatedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"shopify", z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+declare const deleteArticle: _keystrokehq_core0.Operation<z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  deletedArticleId: z.ZodString;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"shopify", z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  SHOPIFY_STORE_DOMAIN: z.ZodString;
+  SHOPIFY_ACCESS_TOKEN: z.ZodString;
+}, z.core.$strip>>[] | undefined>], undefined>;
+//#endregion
+export { createArticle, deleteArticle, getArticle, listArticles, updateArticle };

package/dist/articles.mjs

@@ -0,0 +1,252 @@
+import { shopifyArticleSchema, shopifyConnectionNodesSchema, shopifyGlobalIdSchema, shopifyUserErrorSchema } from "./schemas.mjs";
+import { createShopifyClient } from "./client.mjs";
+import { t as shopifyOperation } from "./factory-DC-gY8L0.mjs";
+import { n as omitUndefined, r as shopifyPageInputSchema, t as assertNoUserErrors } from "./operation-helpers-CKEDIx0o.mjs";
+import { z } from "zod";
+
+//#region src/articles.ts
+const articleSelection = `
+  id
+  title
+  handle
+  blog {
+    
+  id
+  title
+  handle
+  createdAt
+  updatedAt
+  commentPolicy
+  templateSuffix
+
+  }
+  author {
+    name
+  }
+  body
+  summary
+  tags
+  image {
+    url
+    altText
+  }
+  publishedAt
+  updatedAt
+`;
+const articleMutationInputSchema = z.object({
+	blogId: shopifyGlobalIdSchema.optional(),
+	title: z.string().min(1).optional(),
+	handle: z.string().min(1).optional(),
+	body: z.string().optional(),
+	summary: z.string().optional(),
+	authorName: z.string().optional(),
+	isPublished: z.boolean().optional(),
+	publishDate: z.iso.datetime().optional(),
+	tags: z.array(z.string()).optional()
+});
+const articleResponseSchema = z.object({
+	id: shopifyGlobalIdSchema,
+	title: z.string(),
+	handle: z.string(),
+	blog: z.object({
+		id: shopifyGlobalIdSchema,
+		title: z.string(),
+		handle: z.string(),
+		createdAt: z.iso.datetime().optional(),
+		updatedAt: z.iso.datetime().optional(),
+		commentPolicy: z.string().nullable().optional(),
+		templateSuffix: z.string().nullable().optional()
+	}).nullable().optional(),
+	author: z.object({ name: z.string().nullable().optional() }).nullable().optional(),
+	body: z.string().nullable().optional(),
+	summary: z.string().nullable().optional(),
+	tags: z.array(z.string()).optional(),
+	image: z.object({
+		url: z.url(),
+		altText: z.string().nullable().optional()
+	}).nullable().optional(),
+	publishedAt: z.iso.datetime().nullable().optional(),
+	updatedAt: z.iso.datetime().optional()
+});
+const articleMutationPayloadSchema = z.object({
+	article: articleResponseSchema.nullable(),
+	userErrors: z.array(shopifyUserErrorSchema.extend({ code: z.string().optional() }))
+});
+const listArticlesResponseSchema = z.object({ articles: shopifyConnectionNodesSchema(articleResponseSchema) });
+const getArticleResponseSchema = z.object({ article: articleResponseSchema.nullable() });
+const deleteArticleResponseSchema = z.object({
+	deletedArticleId: shopifyGlobalIdSchema.nullable(),
+	userErrors: z.array(shopifyUserErrorSchema.extend({ code: z.string().optional() }))
+});
+function normalizeArticle(article) {
+	return {
+		id: article.id,
+		title: article.title,
+		handle: article.handle,
+		blog: article.blog ?? null,
+		author: article.author?.name ?? null,
+		body: article.body ?? null,
+		summary: article.summary ?? null,
+		tags: article.tags,
+		image: article.image ?? null,
+		publishedAt: article.publishedAt ?? null,
+		updatedAt: article.updatedAt
+	};
+}
+function buildArticleInput(input) {
+	return omitUndefined({
+		blogId: input.blogId,
+		title: input.title,
+		handle: input.handle,
+		body: input.body,
+		summary: input.summary,
+		author: input.authorName ? { name: input.authorName } : void 0,
+		isPublished: input.isPublished,
+		publishDate: input.publishDate,
+		tags: input.tags
+	});
+}
+const listArticles = shopifyOperation({
+	id: "list_shopify_articles",
+	name: "List Shopify Articles",
+	description: "List blog articles from the connected Shopify store.",
+	input: shopifyPageInputSchema,
+	output: shopifyConnectionNodesSchema(shopifyArticleSchema),
+	run: async (input, credentials) => {
+		const response = await createShopifyClient(credentials).graphql(`
+        query ListArticles($first: Int!, $after: String, $query: String) {
+          articles(first: $first, after: $after, query: $query) {
+            nodes {
+              ${articleSelection}
+            }
+            pageInfo {
+              hasNextPage
+              hasPreviousPage
+              startCursor
+              endCursor
+            }
+          }
+        }
+      `, listArticlesResponseSchema, { variables: {
+			first: input.first,
+			...input.after ? { after: input.after } : {},
+			...input.query ? { query: input.query } : {}
+		} });
+		return {
+			nodes: response.articles.nodes.map(normalizeArticle),
+			pageInfo: response.articles.pageInfo
+		};
+	}
+});
+const getArticle = shopifyOperation({
+	id: "get_shopify_article",
+	name: "Get Shopify Article",
+	description: "Retrieve a single Shopify article by its global ID.",
+	input: z.object({ id: shopifyGlobalIdSchema }),
+	output: shopifyArticleSchema,
+	run: async (input, credentials) => {
+		const response = await createShopifyClient(credentials).graphql(`
+        query GetArticle($id: ID!) {
+          article(id: $id) {
+            ${articleSelection}
+          }
+        }
+      `, getArticleResponseSchema, { variables: { id: input.id } });
+		if (!response.article) throw new Error(`Shopify article not found: ${input.id}`);
+		return normalizeArticle(response.article);
+	}
+});
+const createArticle = shopifyOperation({
+	id: "create_shopify_article",
+	name: "Create Shopify Article",
+	description: "Create an article in the connected Shopify store.",
+	needsApproval: true,
+	input: articleMutationInputSchema.extend({
+		blogId: shopifyGlobalIdSchema,
+		title: z.string().min(1)
+	}),
+	output: shopifyArticleSchema,
+	run: async (input, credentials) => {
+		const response = await createShopifyClient(credentials).graphql(`
+        mutation CreateArticle($article: ArticleCreateInput!) {
+          articleCreate(article: $article) {
+            article {
+              ${articleSelection}
+            }
+            userErrors {
+              code
+              field
+              message
+            }
+          }
+        }
+      `, z.object({ articleCreate: articleMutationPayloadSchema }), { variables: { article: buildArticleInput(input) } });
+		assertNoUserErrors(response.articleCreate.userErrors);
+		if (!response.articleCreate.article) throw new Error("Shopify did not return the created article.");
+		return normalizeArticle(response.articleCreate.article);
+	}
+});
+const updateArticle = shopifyOperation({
+	id: "update_shopify_article",
+	name: "Update Shopify Article",
+	description: "Update a Shopify article by its global ID.",
+	needsApproval: true,
+	input: articleMutationInputSchema.extend({
+		id: shopifyGlobalIdSchema,
+		redirectNewHandle: z.boolean().optional()
+	}),
+	output: shopifyArticleSchema,
+	run: async (input, credentials) => {
+		const response = await createShopifyClient(credentials).graphql(`
+        mutation UpdateArticle($id: ID!, $article: ArticleUpdateInput!) {
+          articleUpdate(id: $id, article: $article) {
+            article {
+              ${articleSelection}
+            }
+            userErrors {
+              code
+              field
+              message
+            }
+          }
+        }
+      `, z.object({ articleUpdate: articleMutationPayloadSchema }), { variables: {
+			id: input.id,
+			article: omitUndefined({
+				...buildArticleInput(input),
+				redirectNewHandle: input.redirectNewHandle
+			})
+		} });
+		assertNoUserErrors(response.articleUpdate.userErrors);
+		if (!response.articleUpdate.article) throw new Error(`Shopify did not return the updated article: ${input.id}`);
+		return normalizeArticle(response.articleUpdate.article);
+	}
+});
+const deleteArticle = shopifyOperation({
+	id: "delete_shopify_article",
+	name: "Delete Shopify Article",
+	description: "Delete a Shopify article by its global ID.",
+	needsApproval: true,
+	input: z.object({ id: shopifyGlobalIdSchema }),
+	output: z.object({ deletedArticleId: shopifyGlobalIdSchema }),
+	run: async (input, credentials) => {
+		const response = await createShopifyClient(credentials).graphql(`
+        mutation DeleteArticle($id: ID!) {
+          articleDelete(id: $id) {
+            deletedArticleId
+            userErrors {
+              code
+              field
+              message
+            }
+          }
+        }
+      `, z.object({ articleDelete: deleteArticleResponseSchema }), { variables: { id: input.id } });
+		assertNoUserErrors(response.articleDelete.userErrors);
+		if (!response.articleDelete.deletedArticleId) throw new Error(`Shopify did not confirm article deletion: ${input.id}`);
+		return { deletedArticleId: response.articleDelete.deletedArticleId };
+	}
+});
+
+//#endregion
+export { createArticle, deleteArticle, getArticle, listArticles, updateArticle };