@shopify/shopify-api 12.3.0 → 13.1.0

package/rest/load-rest-resources.ts

@@ -0,0 +1,58 @@
+import type {ShopifyClients} from '../lib';
+import {ConfigInterface} from '../lib/base-types';
+import {logger} from '../lib/logger';
+
+import {Base} from './base';
+import {ShopifyRestResources} from './types';
+
+export interface LoadRestResourcesParams<
+  Resources extends ShopifyRestResources,
+> {
+  resources: Resources;
+  config: ConfigInterface;
+  RestClient: ShopifyClients['Rest'];
+}
+
+export function loadRestResources<Resources extends ShopifyRestResources>({
+  resources,
+  config,
+  RestClient,
+}: LoadRestResourcesParams<Resources>): Resources {
+  const firstResource = Object.keys(resources)[0];
+  if (config.apiVersion !== resources[firstResource].apiVersion) {
+    logger(config).warning(
+      `Loading REST resources for API version ${resources[firstResource].apiVersion}, which doesn't match the default ${config.apiVersion}`,
+    );
+  }
+
+  return Object.fromEntries(
+    Object.entries(resources).map(([name, resource]) => {
+      class NewResource extends resource {}
+
+      NewResource.setClassProperties({
+        Client: RestClient,
+        config,
+      });
+
+      Object.entries(NewResource.hasOne).map(([_attribute, klass]) => {
+        (klass as typeof Base).setClassProperties({
+          Client: RestClient,
+          config,
+        });
+      });
+
+      Object.entries(NewResource.hasMany).map(([_attribute, klass]) => {
+        (klass as typeof Base).setClassProperties({
+          Client: RestClient,
+          config,
+        });
+      });
+
+      Reflect.defineProperty(NewResource, 'name', {
+        value: name,
+      });
+
+      return [name, NewResource];
+    }),
+  ) as Resources;
+}

package/rest/types.ts

@@ -0,0 +1,19 @@
+export type IdSet = Record<string, string | number | null>;
+
+export type ParamSet = Record<string, any>;
+
+export type Body = Record<string, any>;
+
+export interface ResourcePath {
+  http_method: string;
+  operation: string;
+  ids: string[];
+  path: string;
+}
+
+export type ShopifyRestResources = Record<string, any>;
+
+export interface ResourceNames {
+  singular: string;
+  plural: string;
+}

package/runtime/crypto/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './utils';

package/runtime/crypto/types.ts

@@ -0,0 +1,4 @@
+export enum HashFormat {
+  Base64 = 'base64',
+  Hex = 'hex',
+}

package/runtime/crypto/utils.ts

@@ -0,0 +1,120 @@
+import {ShopifyError} from '../../lib/error';
+
+import {HashFormat} from './types';
+
+type HMACSecret = string | ArrayBuffer;
+
+const enc = new TextEncoder();
+
+function getCryptoLib(): Crypto {
+  return typeof (crypto as any)?.webcrypto === 'undefined'
+    ? crypto
+    : (crypto as any).webcrypto;
+}
+
+function hmacKeyData(secret: HMACSecret): BufferSource {
+  return typeof secret === 'string' ? enc.encode(secret) : secret;
+}
+
+export async function createSHA256HMAC(
+  secret: HMACSecret,
+  payload: string,
+  returnFormat: HashFormat = HashFormat.Base64,
+): Promise<string> {
+  const cryptoLib = getCryptoLib();
+  const key = await cryptoLib.subtle.importKey(
+    'raw',
+    hmacKeyData(secret),
+    {
+      name: 'HMAC',
+      hash: {name: 'SHA-256'},
+    },
+    false,
+    ['sign'],
+  );
+
+  const signature = await cryptoLib.subtle.sign(
+    'HMAC',
+    key,
+    enc.encode(payload),
+  );
+  return returnFormat === HashFormat.Base64
+    ? asBase64(signature)
+    : asHex(signature);
+}
+
+export async function deriveSHA256HMACKey(
+  secret: string,
+  info: string,
+): Promise<ArrayBuffer> {
+  const cryptoLib = getCryptoLib();
+  const keyMaterial = await cryptoLib.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    'HKDF',
+    false,
+    ['deriveBits'],
+  );
+
+  return cryptoLib.subtle.deriveBits(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(0),
+      info: enc.encode(info),
+    },
+    keyMaterial,
+    256,
+  );
+}
+
+export function asHex(buffer: ArrayBuffer | Uint8Array): string {
+  return [...new Uint8Array(buffer)]
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+const LookupTable =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+export function asBase64(buffer: ArrayBuffer | Uint8Array): string {
+  let output = '';
+
+  const input = new Uint8Array(buffer);
+  for (let i = 0; i < input.length; ) {
+    const byte1 = input[i++];
+    const byte2 = input[i++];
+    const byte3 = input[i++];
+
+    const enc1 = byte1 >> 2;
+    const enc2 = ((byte1 & 0b00000011) << 4) | (byte2 >> 4);
+    let enc3 = ((byte2 & 0b00001111) << 2) | (byte3 >> 6);
+    let enc4 = byte3 & 0b00111111;
+
+    if (isNaN(byte2)) {
+      enc3 = 64;
+    }
+    if (isNaN(byte3)) {
+      enc4 = 64;
+    }
+
+    output +=
+      LookupTable[enc1] +
+      LookupTable[enc2] +
+      LookupTable[enc3] +
+      LookupTable[enc4];
+  }
+  return output;
+}
+
+export function hashString(str: string, returnFormat: HashFormat): string {
+  const buffer = new TextEncoder().encode(str);
+
+  switch (returnFormat) {
+    case HashFormat.Base64:
+      return asBase64(buffer);
+    case HashFormat.Hex:
+      return asHex(buffer);
+    default:
+      throw new ShopifyError(`Unrecognized hash format '${returnFormat}'`);
+  }
+}

package/runtime/http/cookies.ts

@@ -0,0 +1,245 @@
+// import type {Headers} from "./headers";
+import {createSHA256HMAC, deriveSHA256HMACKey} from '../crypto/utils';
+
+import {splitN} from './utils';
+import {getHeader, getHeaders, removeHeader, addHeader} from './headers';
+
+import type {NormalizedRequest, NormalizedResponse} from '.';
+
+export interface CookieData {
+  name: string;
+  value: string;
+  /**
+   * a number representing the milliseconds from Date.now() for expiry
+   */
+  maxAge?: number;
+  /**
+   * a Date object indicating the cookie's expiration
+   * date (expires at the end of session by default).
+   */
+  expires?: Date;
+  /**
+   * a string indicating the path of the cookie (/ by default).
+   */
+  path?: string;
+  /**
+   * a string indicating the domain of the cookie (no default).
+   */
+  domain?: string;
+  /**
+   * a boolean indicating whether the cookie is only to be sent
+   * over HTTPS (false by default for HTTP, true by default for HTTPS).
+   */
+  secure?: boolean;
+  /**
+   * a boolean indicating whether the cookie is only to be sent over HTTP(S),
+   * and not made available to client JavaScript (true by default).
+   */
+  httpOnly?: boolean;
+  /**
+   * a boolean or string indicating whether the cookie is a "same site" cookie (false by default).
+   * This can be set to 'strict', 'lax', or true (which maps to 'strict').
+   */
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+
+export type CookieJar = Record<string, CookieData>;
+
+const COOKIE_SIGNING_INFO = 'shopify-app-js/cookie-signing/v1';
+
+async function createCookieSignature(
+  key: string,
+  value: string,
+): Promise<string> {
+  const cookieSigningKey = await deriveSHA256HMACKey(key, COOKIE_SIGNING_INFO);
+  return createSHA256HMAC(cookieSigningKey, value);
+}
+
+const signatureEncoder = new TextEncoder();
+
+function safelyCompareSignatures(signatureA: string, signatureB: string) {
+  const buffA = signatureEncoder.encode(signatureA);
+  const buffB = signatureEncoder.encode(signatureB);
+
+  if (buffA.length !== buffB.length) return false;
+
+  let out = 0;
+  for (let i = 0; i < buffA.length; i++) {
+    out |= buffA[i] ^ buffB[i];
+  }
+
+  return out === 0;
+}
+
+interface CookiesOptions {
+  keys: string[];
+  // Ignored. Only for type-compatibility with the node package for now.
+  secure: boolean;
+}
+export class Cookies {
+  static parseCookies(hdrs: string[]): CookieJar {
+    const entries = hdrs
+      .filter((hdr) => hdr.trim().length > 0)
+      .map((cookieDef) => {
+        const [keyval, ...opts] = cookieDef.split(';');
+        const [name, value] = splitN(keyval, '=', 2).map((value) =>
+          value.trim(),
+        );
+        return [
+          name,
+          {
+            name,
+            value,
+            ...Object.fromEntries(
+              opts.map((opt) =>
+                splitN(opt, '=', 2).map((value) => value.trim()),
+              ),
+            ),
+          },
+        ];
+      });
+    const jar = Object.fromEntries(entries) as CookieJar;
+    for (const cookie of Object.values(jar)) {
+      if (typeof cookie.expires === 'string') {
+        cookie.expires = new Date(cookie.expires);
+      }
+    }
+    return jar;
+  }
+
+  static encodeCookie(data: CookieData): string {
+    let result = '';
+    result += `${data.name}=${data.value};`;
+    result += Object.entries(data)
+      .filter(([key]) => !['name', 'value', 'expires'].includes(key))
+      .map(([key, value]) => `${key}=${value}`)
+      .join('; ');
+    if (data.expires) {
+      result += ';';
+      result += `expires=${data.expires.toUTCString()}`;
+    }
+    return result;
+  }
+
+  receivedCookieJar: CookieJar = {};
+  outgoingCookieJar: CookieJar = {};
+  private keys: string[] = [];
+
+  constructor(
+    request: NormalizedRequest,
+    public response: NormalizedResponse,
+    {keys = []}: Partial<CookiesOptions> = {},
+  ) {
+    if (keys) this.keys = keys;
+
+    const cookieReqHdr = getHeader(request.headers, 'Cookie') ?? '';
+    this.receivedCookieJar = Cookies.parseCookies(cookieReqHdr.split(';'));
+    const cookieResHdr = getHeaders(response.headers, 'Set-Cookie') ?? [];
+    this.outgoingCookieJar = Cookies.parseCookies(cookieResHdr);
+  }
+
+  toHeaders(): string[] {
+    return Object.values(this.outgoingCookieJar).map((cookie) =>
+      Cookies.encodeCookie(cookie),
+    );
+  }
+
+  updateHeader() {
+    if (!this.response.headers) {
+      this.response.headers = {};
+    }
+    removeHeader(this.response.headers, 'Set-Cookie');
+    this.toHeaders().map((hdr) =>
+      addHeader(this.response.headers!, 'Set-Cookie', hdr),
+    );
+  }
+
+  get(name: string): string | undefined {
+    return this.receivedCookieJar[name]?.value;
+  }
+
+  deleteCookie(name: string) {
+    this.set(name, '', {
+      path: '/',
+      expires: new Date(0),
+    });
+  }
+
+  async getAndVerify(name: string): Promise<string | undefined> {
+    const value = this.get(name);
+    if (!value) return undefined;
+    if (!(await this.isSignedCookieValid(name))) {
+      return undefined;
+    }
+    return value;
+  }
+
+  private get canSign() {
+    return this.keys?.length > 0;
+  }
+
+  set(name: string, value: string, opts: Partial<CookieData> = {}): void {
+    this.outgoingCookieJar[name] = {
+      ...opts,
+      name,
+      value,
+    };
+    this.updateHeader();
+  }
+
+  async setAndSign(
+    name: string,
+    value: string,
+    opts: Partial<CookieData> = {},
+  ): Promise<void> {
+    if (!this.canSign) {
+      throw Error('No keys provided for signing.');
+    }
+    this.set(name, value, opts);
+    const sigName = `${name}.sig`;
+    const signature = await createCookieSignature(this.keys[0], value);
+    this.set(sigName, signature, opts);
+    this.updateHeader();
+  }
+
+  async isSignedCookieValid(cookieName: string): Promise<boolean> {
+    const signedCookieName = `${cookieName}.sig`;
+    if (
+      !this.cookieExists(cookieName) ||
+      !this.cookieExists(signedCookieName)
+    ) {
+      this.deleteInvalidCookies(cookieName, signedCookieName);
+      return false;
+    }
+    const cookieValue = this.get(cookieName);
+    const signature = this.get(signedCookieName);
+
+    if (!cookieValue || !signature) {
+      this.deleteInvalidCookies(cookieName, signedCookieName);
+      return false;
+    }
+
+    const allCheckSignatures = await Promise.all(
+      this.keys.map((key) => createCookieSignature(key, cookieValue)),
+    );
+
+    const validSignature = allCheckSignatures.some((checkSignature) =>
+      safelyCompareSignatures(checkSignature, signature),
+    );
+
+    if (!validSignature) {
+      this.deleteInvalidCookies(cookieName, signedCookieName);
+      return false;
+    }
+
+    return true;
+  }
+
+  private cookieExists(cookieName: string) {
+    return Boolean(this.get(cookieName));
+  }
+
+  private deleteInvalidCookies(...cookieNames: string[]): void {
+    cookieNames.forEach((cookieName) => this.deleteCookie(cookieName));
+  }
+}

package/runtime/http/headers.ts

@@ -0,0 +1,164 @@
+import type {Headers} from './types';
+
+/**
+ * Canonicalizes a header name by capitalizing each segment and ensuring consistent hyphenation.
+ *
+ * @param hdr - The header name to canonicalize.
+ * @returns The canonicalized header name.
+ */
+export function canonicalizeHeaderName(hdr: string): string {
+  return hdr.replace(
+    /(^|-)(\w+)/g,
+    (_fullMatch, start, letters) =>
+      start +
+      letters.slice(0, 1).toUpperCase() +
+      letters.slice(1).toLowerCase(),
+  );
+}
+
+/**
+ * Retrieves all values associated with a canonicalized header name from the headers object.
+ *
+ * @param headers - The headers object or undefined.
+ * @param needle_ - The header name to search for.
+ * @returns An array of header values associated with the canonicalized header name.
+ */
+export function getHeaders(
+  headers: Headers | undefined,
+  needle_: string,
+): string[] {
+  const result: string[] = [];
+  if (!headers) return result;
+  const needle = canonicalizeHeaderName(needle_);
+  for (const [key, values] of Object.entries(headers)) {
+    if (canonicalizeHeaderName(key) !== needle) continue;
+    if (Array.isArray(values)) {
+      result.push(...values);
+    } else {
+      result.push(values);
+    }
+  }
+  return result;
+}
+
+/**
+ * Retrieves the first value associated with a canonicalized header name from the headers object.
+ *
+ * @param headers - The headers object or undefined.
+ * @param needle - The header name to search for.
+ * @returns The first value associated with the canonicalized header name, or undefined if not found.
+ */
+export function getHeader(
+  headers: Headers | undefined,
+  needle: string,
+): string | undefined {
+  if (!headers) return undefined;
+  return getHeaders(headers, needle)?.[0];
+}
+/**
+ * Sets a header to a single value, canonicalizing the header name.
+ *
+ * @param headers - The headers object.
+ * @param key - The header name to set.
+ * @param value - The value to assign to the header.
+ */
+export function setHeader(headers: Headers, key: string, value: string) {
+  canonicalizeHeaders(headers);
+  headers[canonicalizeHeaderName(key)] = [value];
+}
+/**
+ * Adds a value to an existing header, creating a new array if necessary, and canonicalizing the header name.
+ *
+ * @param headers - The headers object.
+ * @param key - The header name to add to.
+ * @param value - The value to add.
+ */
+export function addHeader(headers: Headers, key: string, value: string) {
+  canonicalizeHeaders(headers);
+  const canonKey = canonicalizeHeaderName(key);
+  let list = headers[canonKey];
+  if (!list) {
+    list = [];
+  } else if (!Array.isArray(list)) {
+    list = [list];
+  }
+  headers[canonKey] = list;
+  list.push(value);
+}
+
+/**
+ * Canonicalizes a header value, converting numbers to strings.
+ *
+ * @param value - The value to canonicalize.
+ * @returns The canonicalized value as a string.
+ */
+function canonicalizeValue(value: any): any {
+  if (typeof value === 'number') return value.toString();
+  return value;
+}
+
+/**
+ * Canonicalizes all headers in the headers object by ensuring consistent header names and values.
+ *
+ * @param hdr - The headers object to canonicalize.
+ * @returns The headers object with canonicalized header names and values.
+ */
+export function canonicalizeHeaders(hdr: Headers): Headers {
+  for (const [key, values] of Object.entries(hdr)) {
+    const canonKey = canonicalizeHeaderName(key);
+    if (!hdr[canonKey]) hdr[canonKey] = [];
+    if (!Array.isArray(hdr[canonKey]))
+      hdr[canonKey] = [canonicalizeValue(hdr[canonKey])];
+    if (key === canonKey) continue;
+    delete hdr[key];
+    (hdr[canonKey] as any).push(
+      ...[values].flat().map((value) => canonicalizeValue(value)),
+    );
+  }
+  return hdr;
+}
+
+/**
+ * Removes a header from the headers object.
+ *
+ * @param headers - The headers object.
+ * @param needle - The header name to remove.
+ */
+export function removeHeader(headers: Headers, needle: string) {
+  canonicalizeHeaders(headers);
+  const canonKey = canonicalizeHeaderName(needle);
+  delete headers[canonKey];
+}
+
+/**
+ * Converts a headers object into an array of tuples, where each tuple represents a header name and value.
+ *
+ * @param {Object|string[][]} headers - The headers object or undefined/null.
+ * @returns {string[][]} An array of tuples where each tuple contains a header name and its corresponding value.
+ *
+ * @example
+ * // Example headers object
+ * const headers = {
+ *   'Set-Cookie': 'a=b',
+ *   'Set-Cookie': 'x=y'
+ * };
+ *
+ * // Converted to an array of tuples
+ * const result = convertHeadersToTuples(headers);
+ * console.log(result);
+ * // Output: [
+ * //   ["Set-Cookie", "a=b"],
+ * //   ["Set-Cookie", "x=y"]
+ * // ]
+ */
+export function flatHeaders(
+  headers: Headers | undefined | null,
+): [string, string][] {
+  if (!headers) return [];
+
+  return Object.entries(headers).flatMap(([header, values]) =>
+    Array.isArray(values)
+      ? values.map((value): [string, string] => [header, value])
+      : [[header, values]],
+  );
+}

package/runtime/http/index.ts

@@ -0,0 +1,77 @@
+import type {
+  AbstractFetchFunc,
+  AbstractConvertRequestFunc,
+  AbstractConvertIncomingResponseFunc,
+  AbstractConvertResponseFunc,
+  NormalizedResponse,
+  AbstractConvertHeadersFunc,
+} from './types';
+
+export * from './cookies';
+export * from './headers';
+export * from './utils';
+
+export * from './types';
+
+export function isOK(resp: NormalizedResponse) {
+  // https://fetch.spec.whatwg.org/#ok-status
+  return resp.statusCode >= 200 && resp.statusCode <= 299;
+}
+
+// We ignore mutable export linting errors because we explicitly want these abstract functions to be overwritten.
+
+// eslint-disable-next-line import/no-mutable-exports
+export let abstractFetch: AbstractFetchFunc = () => {
+  throw new Error(
+    "Missing adapter implementation for 'abstractFetch' - make sure to import the appropriate adapter for your platform",
+  );
+};
+export function setAbstractFetchFunc(func: AbstractFetchFunc) {
+  abstractFetch = func;
+}
+
+// eslint-disable-next-line import/no-mutable-exports
+export let abstractConvertRequest: AbstractConvertRequestFunc = () => {
+  throw new Error(
+    "Missing adapter implementation for 'abstractConvertRequest' - make sure to import the appropriate adapter for your platform",
+  );
+};
+export function setAbstractConvertRequestFunc(
+  func: AbstractConvertRequestFunc,
+) {
+  abstractConvertRequest = func;
+}
+
+// By default we just return an empty NormalizedResponse because not all adapters will need to convert an incoming response
+// eslint-disable-next-line import/no-mutable-exports
+export let abstractConvertIncomingResponse: AbstractConvertIncomingResponseFunc =
+  () => Promise.resolve({} as NormalizedResponse);
+export function setAbstractConvertIncomingResponseFunc(
+  func: AbstractConvertIncomingResponseFunc,
+) {
+  abstractConvertIncomingResponse = func;
+}
+
+// eslint-disable-next-line import/no-mutable-exports
+export let abstractConvertResponse: AbstractConvertResponseFunc = () => {
+  throw new Error(
+    "Missing adapter implementation for 'abstractConvertResponse' - make sure to import the appropriate adapter for your platform",
+  );
+};
+export function setAbstractConvertResponseFunc(
+  func: AbstractConvertResponseFunc,
+) {
+  abstractConvertResponse = func;
+}
+
+// eslint-disable-next-line import/no-mutable-exports
+export let abstractConvertHeaders: AbstractConvertHeadersFunc = () => {
+  throw new Error(
+    "Missing adapter implementation for 'abstractConvertHeaders' - make sure to import the appropriate adapter for your platform",
+  );
+};
+export function setAbstractConvertHeadersFunc(
+  func: AbstractConvertHeadersFunc,
+) {
+  abstractConvertHeaders = func;
+}