get_fulfillment

Instructions

Implementation Reference

• src/tools/fulfillment.ts:334-379 (registration)

  Registration of 'get_fulfillment' tool via server.tool() with the schema and handler.

  server.tool(
    "get_fulfillment",
    "Fetch a single fulfillment (a shipment record produced by create_fulfillment) by GID. Returns its status (SUCCESS/CANCELLED/etc.), tracking entries (carrier, number, URL), the parent order, and timestamps. Use after create_fulfillment to confirm the shipment took, or when a webhook delivers a fulfillment GID and you need the details.",
    getFulfillmentSchema,
    async (args) => {
      const data = await client.graphql<{ fulfillment: FulfillmentNode | null }>(
        GET_FULFILLMENT_QUERY,
        { id: args.id },
      );
      if (!data.fulfillment) {
        return {
          content: [
            { type: "text" as const, text: `Fulfillment not found: ${args.id}` },
          ],
        };
      }
      const f = data.fulfillment;
      const tracking = f.trackingInfo
        .map((t) => {
          const parts = [t.company, t.number, t.url].filter(Boolean);
          return parts.length > 0 ? `    - ${parts.join(" | ")}` : "    - (empty)";
        })
        .join("\n");
      return {
        content: [
          {
            type: "text" as const,
            text: [
              `${f.name} [${f.status}]`,
              `  ID: ${f.id}`,
              f.order ? `  Order: ${f.order.name} (${f.order.id})` : "",
              f.totalQuantity !== null && f.totalQuantity !== undefined
                ? `  Total quantity: ${f.totalQuantity}`
                : "",
              "  Tracking:",
              tracking || "    (none)",
              `  Created: ${f.createdAt}`,
              `  Updated: ${f.updatedAt}`,
            ]
              .filter(Boolean)
              .join("\n"),
          },
        ],
      };
    },
  );

• src/tools/fulfillment.ts:338-378 (handler)

  Handler function that calls GraphQL query GET_FULFILLMENT_QUERY and formats the response (status, tracking, order, timestamps).

  async (args) => {
    const data = await client.graphql<{ fulfillment: FulfillmentNode | null }>(
      GET_FULFILLMENT_QUERY,
      { id: args.id },
    );
    if (!data.fulfillment) {
      return {
        content: [
          { type: "text" as const, text: `Fulfillment not found: ${args.id}` },
        ],
      };
    }
    const f = data.fulfillment;
    const tracking = f.trackingInfo
      .map((t) => {
        const parts = [t.company, t.number, t.url].filter(Boolean);
        return parts.length > 0 ? `    - ${parts.join(" | ")}` : "    - (empty)";
      })
      .join("\n");
    return {
      content: [
        {
          type: "text" as const,
          text: [
            `${f.name} [${f.status}]`,
            `  ID: ${f.id}`,
            f.order ? `  Order: ${f.order.name} (${f.order.id})` : "",
            f.totalQuantity !== null && f.totalQuantity !== undefined
              ? `  Total quantity: ${f.totalQuantity}`
              : "",
            "  Tracking:",
            tracking || "    (none)",
            `  Created: ${f.createdAt}`,
            `  Updated: ${f.updatedAt}`,
          ]
            .filter(Boolean)
            .join("\n"),
        },
      ],
    };
  },

• src/tools/fulfillment.ts:208-210 (schema)

  Schema definition for get_fulfillment: requires a single 'id' string parameter (Fulfillment GID).

  const getFulfillmentSchema = {
    id: z.string().describe("Fulfillment GID."),
  };

• src/tools/fulfillment.ts:108-121 (helper)

  GET_FULFILLMENT_QUERY GraphQL query used by the handler to fetch fulfillment details.

  const GET_FULFILLMENT_QUERY = /* GraphQL */ `
    query GetFulfillment($id: ID!) {
      fulfillment(id: $id) {
        id
        status
        name
        createdAt
        updatedAt
        totalQuantity
        trackingInfo { company number url }
        order { id name }
      }
    }
  `;

• src/server.ts:21-21 (helper)

  Import of registerFulfillmentTools in the main server file.

  import { registerFulfillmentTools } from "./tools/fulfillment.js";