Add Customer Account EXAF address types

.changeset/customer-account-exaf-addresses.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Add structured extended address fields to Customer Account order address APIs.

packages/ui-extensions/docs/surfaces/customer-account/build-docs.mjs

@@ -68,6 +68,100 @@ const cleanupTempFiles = async (tempFiles) => {
   );
 };
 
+const customerAccountMailingAddressFields = [
+  {
+    filePath: 'src/surfaces/customer-account/api/shared.ts',
+    syntaxKind: 'PropertySignature',
+    name: 'extendedFields',
+    value: 'AddressExtendedFields',
+    description:
+      'Structured address components for countries and regions that collect them. ' +
+      "The value is `undefined` when structured address data isn't available " +
+      'for the order address. Individual fields are `null` when Shopify has ' +
+      "a structured address record but a specific component wasn't provided.",
+    isOptional: true,
+  },
+  {
+    filePath: 'src/surfaces/customer-account/api/shared.ts',
+    syntaxKind: 'PropertySignature',
+    name: 'addressCode',
+    value: 'string | null',
+    description:
+      'A country-specific address code, such as a short code or postal ' +
+      "delivery code. The value is `null` when the order address doesn't " +
+      'have an address code.',
+    isOptional: true,
+    examples: [
+      {
+        title: 'Example',
+        description: '',
+        tabs: [{code: "'01001-000'", title: 'Example'}],
+      },
+    ],
+  },
+];
+
+const customerAccountMailingAddressValue = `  /**
+   * Structured address components for countries and regions that collect them.
+   * The value is \`undefined\` when structured address data isn't available for
+   * the order address. Individual fields are \`null\` when Shopify has a
+   * structured address record but a specific component wasn't provided.
+   */
+  extendedFields?: AddressExtendedFields;
+
+  /**
+   * A country-specific address code, such as a short code or postal delivery
+   * code. The value is \`null\` when the order address doesn't have an address
+   * code.
+   *
+   * @example '01001-000'
+   */
+  addressCode?: string | null;
+
+`;
+
+const addCustomerAccountMailingAddressDocs = async (generatedDocsV2Path) => {
+  const content = await fs.readFile(generatedDocsV2Path, 'utf8');
+  const generatedDocs = JSON.parse(content);
+  const mailingAddressDocs = generatedDocs.MailingAddress;
+
+  if (!mailingAddressDocs) return;
+
+  const [sourcePath] = Object.keys(mailingAddressDocs);
+  const docs = mailingAddressDocs[sourcePath];
+
+  if (!docs?.members || !docs?.value) return;
+
+  const existingMemberNames = new Set(
+    docs.members.map((member) => member.name),
+  );
+
+  const missingFields = customerAccountMailingAddressFields.filter(
+    (field) => !existingMemberNames.has(field.name),
+  );
+
+  if (missingFields.length > 0) {
+    const address2Index = docs.members.findIndex(
+      (member) => member.name === 'address2',
+    );
+    const insertIndex =
+      address2Index === -1 ? docs.members.length : address2Index + 1;
+    docs.members.splice(insertIndex, 0, ...missingFields);
+  }
+
+  if (!docs.value.includes('extendedFields?: AddressExtendedFields;')) {
+    docs.value = docs.value.replace(
+      '  /**\n   * The city, town, or village of the address.',
+      `${customerAccountMailingAddressValue}  /**\n   * The city, town, or village of the address.`,
+    );
+  }
+
+  await fs.writeFile(
+    generatedDocsV2Path,
+    `${JSON.stringify(generatedDocs, null, 2)}\n`,
+  );
+};
+
 const generateExtensionsDocs = async () => {
   console.log(
     `Building Customer Account UI Extensions docs for ${EXTENSIONS_API_VERSION} version`,
@@ -98,12 +192,16 @@ const generateExtensionsDocs = async () => {
     replaceValue: '',
   });
 
+  const generatedDocsV2Path = path.join(outputDir, generatedDocsDataV2File);
+
   // Replace 'unstable' with the exact API version in relative doc links
   await replaceFileContent({
-    filePaths: path.join(outputDir, generatedDocsDataV2File),
+    filePaths: generatedDocsV2Path,
     searchValue: '/docs/api//unstable/',
     replaceValue: `/docs/api/customer-account-ui-extensions/${EXTENSIONS_API_VERSION}`,
   });
+
+  await addCustomerAccountMailingAddressDocs(generatedDocsV2Path);
 };
 
 let checkoutTempFiles = [];
@@ -126,10 +224,16 @@ try {
   // Generate targets.json
   console.log('Generating targets.json...');
   try {
-    execSync(`node ${path.join(docsPath, 'build-docs-targets-json.mjs')} ${EXTENSIONS_API_VERSION}`, {
-      stdio: 'inherit',
-      cwd: rootPath,
-    });
+    execSync(
+      `node ${path.join(
+        docsPath,
+        'build-docs-targets-json.mjs',
+      )} ${EXTENSIONS_API_VERSION}`,
+      {
+        stdio: 'inherit',
+        cwd: rootPath,
+      },
+    );
     console.log('✅ Generated targets.json');
   } catch (targetsError) {
     console.warn(

packages/ui-extensions/src/surfaces/customer-account/api.ts

@@ -51,6 +51,7 @@ export type {
   GraphQLError,
   SellingPlan,
   StorefrontApiVersion,
+  AddressExtendedFields,
   MailingAddress,
   ApiVersion,
   Capability,

packages/ui-extensions/src/surfaces/customer-account/api/order-status/order-status.ts

@@ -341,17 +341,21 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * are delivered. The value is `undefined` if the order contains only digital products or
    * if a shipping address wasn't required.
    *
-   * Reflects the state at the time the order was placed. Doesn't update if the
-   * customer changes their account address afterward.
+   * Includes structured address fields, such as `addressCode` and `extendedFields`,
+   * when they're available for the order address. Reflects the state at the time
+   * the order was placed. Doesn't update if the customer changes their account
+   * address afterward.
    */
   shippingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /**
    * The billing address associated with the buyer's payment method for the order. The value
    * is `undefined` if the order doesn't have a billing address on file.
    *
-   * Reflects the state at the time the order was placed. Doesn't update if the
-   * customer changes their account address afterward.
+   * Includes structured address fields, such as `addressCode` and `extendedFields`,
+   * when they're available for the order address. Reflects the state at the time
+   * the order was placed. Doesn't update if the customer changes their account
+   * address afterward.
    */
   billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 

packages/ui-extensions/src/surfaces/customer-account/api/shared.ts

@@ -250,6 +250,51 @@ export interface Attribute {
   value: string;
 }
 
+/**
+ * Structured extended address fields for countries and regions that collect
+ * address components separately from the flat address lines. These fields are
+ * available on order shipping and billing addresses when the order was placed
+ * with structured address data.
+ *
+ * @publicDocs
+ */
+export interface AddressExtendedFields {
+  /**
+   * The street name without the building or street number.
+   *
+   * @example 'Avenida Paulista'
+   */
+  streetName?: string | null;
+
+  /**
+   * The building or street number.
+   *
+   * @example '123'
+   */
+  streetNumber?: string | null;
+
+  /**
+   * Additional address information, such as a block, floor, or unit.
+   *
+   * @example '10th floor'
+   */
+  line2?: string | null;
+
+  /**
+   * The district or neighborhood.
+   *
+   * @example 'Bela Vista'
+   */
+  district?: string | null;
+
+  /**
+   * The subdistrict or smaller locality.
+   *
+   * @example 'Centro'
+   */
+  subdistrict?: string | null;
+}
+
 /**
  * A mailing address associated with the order, such as a shipping or billing address.
  *
@@ -300,6 +345,23 @@ export interface MailingAddress {
    */
   address2?: string;
 
+  /**
+   * Structured address components for countries and regions that collect them.
+   * The value is `undefined` when structured address data isn't available for
+   * the order address. Individual fields are `null` when Shopify has a
+   * structured address record but a specific component wasn't provided.
+   */
+  extendedFields?: AddressExtendedFields;
+
+  /**
+   * A country-specific address code, such as a short code or postal delivery
+   * code. The value is `null` when the order address doesn't have an address
+   * code.
+   *
+   * @example '01001-000'
+   */
+  addressCode?: string | null;
+
   /**
    * The city, town, or village of the address.
    *