@wix/sdk 1.3.0 → 1.4.1

package/build/browser/index.mjs

@@ -1,3 +1,73 @@
+// src/ambassador-modules.ts
+import { transformError } from "@wix/metro-runtime/velo";
+var parseMethod = (method) => {
+  switch (method) {
+    case "get":
+    case "GET":
+      return "GET";
+    case "post":
+    case "POST":
+      return "POST";
+    case "put":
+    case "PUT":
+      return "PUT";
+    case "delete":
+    case "DELETE":
+      return "DELETE";
+    case "patch":
+    case "PATCH":
+      return "PATCH";
+    case "head":
+    case "HEAD":
+      return "HEAD";
+    case "options":
+    case "OPTIONS":
+      return "OPTIONS";
+    default:
+      throw new Error(`Unknown method: ${method}`);
+  }
+};
+var toHTTPModule = (factory) => (httpClient) => async (payload) => {
+  let requestOptions;
+  const HTTPFactory = (context) => {
+    requestOptions = factory(payload)(context);
+    if (requestOptions.url === void 0) {
+      throw new Error(
+        "Url was not successfully created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const { method, url, params } = requestOptions;
+    return {
+      ...requestOptions,
+      method: parseMethod(method),
+      url,
+      data: requestOptions.data,
+      params
+    };
+  };
+  try {
+    const response = await httpClient.request(HTTPFactory);
+    if (requestOptions === void 0) {
+      throw new Error(
+        "Request options were not created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const transformations = Array.isArray(requestOptions.transformResponse) ? requestOptions.transformResponse : [requestOptions.transformResponse];
+    let data = response.data;
+    transformations.forEach((transform) => {
+      if (transform) {
+        data = transform(response.data, response.headers);
+      }
+    });
+    return data;
+  } catch (e) {
+    throw transformError(e);
+  }
+};
+var ambassadorModuleOptions = () => ({
+  HTTPHost: self.location.host
+});
+
 // src/common.ts
 var PUBLIC_METADATA_KEY = "__metadata";
 var API_URL = "www.wixapis.com";
@@ -37,16 +107,17 @@ function objectToKeyValue(input) {
 }
 
 // src/rest-modules.ts
-function buildRESTDescriptor(origFunc, publicMetadata, boundFetch) {
+var getDefaultDomain = (method, url) => method === "GET" && !FORCE_WRITE_API_URLS.some((write_url) => url === write_url) ? READ_ONLY_API_URL : API_URL;
+function buildRESTDescriptor(origFunc, publicMetadata, boundFetch, options) {
   return origFunc({
     request: async (factory) => {
-      var _a, _b;
-      const requestOptions = factory({ host: API_URL });
+      var _a, _b, _c;
+      const requestOptions = factory({ host: (options == null ? void 0 : options.HTTPHost) || API_URL });
       let request = requestOptions;
       if (request.method === "GET" && ((_a = request.fallback) == null ? void 0 : _a.length) && request.params.toString().length > 4e3) {
         request = requestOptions.fallback[0];
       }
-      const domain = request.method === "GET" && !FORCE_WRITE_API_URLS.some((url2) => request.url === url2) ? READ_ONLY_API_URL : API_URL;
+      const domain = (_b = options == null ? void 0 : options.HTTPHost) != null ? _b : getDefaultDomain(request.method, request.url);
       let url = `https://${domain}${request.url}`;
       if (request.params && request.params.toString()) {
         url += `?${request.params.toString()}`;
@@ -86,7 +157,7 @@ function buildRESTDescriptor(origFunc, publicMetadata, boundFetch) {
           statusText: res.statusText
         };
       } catch (e) {
-        if ((_b = e.message) == null ? void 0 : _b.includes("fetch is not defined")) {
+        if ((_c = e.message) == null ? void 0 : _c.includes("fetch is not defined")) {
           console.error("Node.js v18+ is required");
         }
         throw e;
@@ -138,10 +209,15 @@ function createClient(config) {
     if (isHostModule(modules) && config.host) {
       return buildHostModule(modules, config.host);
     } else if (typeof modules === "function") {
+      const { module, options } = modules.__isAmbassador ? {
+        module: toHTTPModule(modules),
+        options: ambassadorModuleOptions()
+      } : { module: modules, options: void 0 };
       return buildRESTDescriptor(
-        modules,
+        module,
         metadata != null ? metadata : {},
-        boundFetch
+        boundFetch,
+        options
       );
     } else if (isObject(modules)) {
       return Object.fromEntries(
@@ -745,14 +821,98 @@ function ApiKeyStrategy({
   };
 }
 
+// src/auth/WixAppOAuthStrategy.ts
+function WixAppOAuthStrategy(opts) {
+  let refreshToken = opts.refreshToken;
+  return {
+    getInstallUrl({ redirectUrl }) {
+      return `https://www.wix.com/installer/install?appId=${opts.appId}&redirectUrl=${redirectUrl}`;
+    },
+    async handleOAuthCallback(url, oauthOpts) {
+      const params = new URLSearchParams(new URL(url).search);
+      const state = params.get("state");
+      if (state && (oauthOpts == null ? void 0 : oauthOpts.state) && state !== oauthOpts.state) {
+        throw new Error(
+          `Invalid OAuth callback URL. Expected state to be "${oauthOpts.state}" but got "${state}"`
+        );
+      }
+      const code = params.get("code");
+      const instanceId = params.get("instanceId");
+      if (!code || !instanceId) {
+        throw new Error(
+          "Invalid OAuth callback URL. Make sure you pass the url including the code and instanceId query params."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          code,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "authorization_code"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange authorization code for refresh token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        instanceId,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token
+      };
+    },
+    async getAuthHeaders() {
+      if (!refreshToken) {
+        throw new Error(
+          "Missing refresh token. Either pass it to the WixAppOAuthStrategy or use the handleOAuthCallback method to retrieve it."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          refresh_token: refreshToken,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "refresh_token"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange refresh token for access token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        headers: {
+          Authorization: tokens.access_token
+        }
+      };
+    }
+  };
+}
+
 // src/index.ts
 export * from "@wix/sdk-types";
 export {
+  API_URL,
   ApiKeyStrategy,
   LoginState,
   OAuthStrategy,
   TokenRole,
+  WixAppOAuthStrategy,
   createClient,
   decodeText,
+  getDefaultDomain,
   media
 };

package/build/index.d.mts

@@ -7,6 +7,36 @@ import { authentication } from '@wix/identity';
 type PublicMetadata = {
     PACKAGE_NAME?: string;
 };
+declare const API_URL = "www.wixapis.com";
+
+declare const getDefaultDomain: (method: string, url: string) => "www.wixapis.com" | "readonly.wixapis.com";
+
+type RequestContext = {
+    isSSR: boolean;
+    host: string;
+    protocol?: string;
+};
+/**
+ * Ambassador request options types are copied mostly from AxiosRequestConfig.
+ * They are copied and not imported to reduce the amount of dependencies (to reduce install time).
+ * https://github.com/axios/axios/blob/3f53eb6960f05a1f88409c4b731a40de595cb825/index.d.ts#L307-L315
+ */
+type Method = 'get' | 'GET' | 'delete' | 'DELETE' | 'head' | 'HEAD' | 'options' | 'OPTIONS' | 'post' | 'POST' | 'put' | 'PUT' | 'patch' | 'PATCH' | 'purge' | 'PURGE' | 'link' | 'LINK' | 'unlink' | 'UNLINK';
+type ResponseTransformer = (data: any, headers?: any) => any;
+type AmbassadorRequestOptions<T = any> = {
+    _?: T;
+    url?: string;
+    method?: Method;
+    params?: any;
+    data?: any;
+    transformResponse?: ResponseTransformer | ResponseTransformer[];
+};
+type AmbassadorFactory<Request, Response> = {
+    (payload: Request): (context: RequestContext) => AmbassadorRequestOptions<Response>;
+    __isAmbassador: boolean;
+};
+type AmbassadorFunctionDescriptor<Request = any, Response = any> = AmbassadorFactory<Request, Response>;
+type BuildAmbassadorFunction<T extends AmbassadorFunctionDescriptor> = T extends AmbassadorFunctionDescriptor<infer Request, infer Response> ? (req: Request) => Promise<Response> : never;
 
 type Headers = {
     Authorization: string;
@@ -17,10 +47,13 @@ type Headers = {
  * Any non-descriptor properties are removed from the returned object, including descriptors that
  * do not match the given host (as they will not work with the given host).
  */
-type BuildDescriptors<T extends Descriptors, H extends Host<any> | undefined> = BuildRESTDescriptors<T> & (H extends Host<any> ? BuildHostDescriptors<T> : {});
+type BuildDescriptors<T extends Descriptors, H extends Host<any> | undefined> = BuildRESTDescriptors<T> & BuildAmbassadorDescriptors<T> & (H extends Host<any> ? BuildHostDescriptors<T> : {});
 type BuildRESTDescriptors<T extends Descriptors> = T extends RESTFunctionDescriptor ? BuildRESTFunction<T> : ConditionalExcept<{
     [Key in keyof T]: T[Key] extends Descriptors ? BuildRESTDescriptors<T[Key]> : never;
 }, EmptyObject>;
+type BuildAmbassadorDescriptors<T extends Descriptors> = T extends AmbassadorFunctionDescriptor ? BuildAmbassadorFunction<T> : ConditionalExcept<{
+    [Key in keyof T]: T[Key] extends Descriptors ? BuildAmbassadorDescriptors<T[Key]> : never;
+}, EmptyObject>;
 type BuildHostDescriptors<T extends Descriptors> = T extends HostModule<any, any> ? HostModuleAPI<T> : ConditionalExcept<{
     [Key in keyof T]: T[Key] extends Descriptors ? BuildHostDescriptors<T[Key]> : never;
 }, EmptyObject>;
@@ -29,7 +62,7 @@ type BuildHostDescriptors<T extends Descriptors> = T extends HostModule<any, any
  * can either be a REST module or a host module.
  * This type is recursive, so it can describe nested modules.
  */
-type Descriptors = RESTFunctionDescriptor | HostModule<any, any> | {
+type Descriptors = RESTFunctionDescriptor | AmbassadorFunctionDescriptor | HostModule<any, any> | {
     [key: string]: Descriptors | PublicMetadata | any;
 };
 /**
@@ -222,4 +255,58 @@ declare function ApiKeyStrategy({ siteId, accountId, apiKey, }: {
     apiKey: string;
 } & Context): IApiKeyStrategy;
 
-export { AccessToken, ApiKeyStrategy, AssertHostMatches, BuildDescriptors, CalculateNextState, Descriptors, IApiKeyStrategy, IOAuthStrategy, LoginParams, LoginState, OAuthStrategy, OauthData, OauthPKCE, ProcessableState, RefreshToken, RegisterParams, StateMachine, Token, TokenResponse, TokenRole, Tokens, WixClient, createClient, decodeText, media };
+type WixAppOAuthStrategy = AuthenticationStrategy & {
+    getInstallUrl({ redirectUrl }: {
+        redirectUrl: string;
+    }): string;
+    handleOAuthCallback(url: string, opts?: {
+        state: string;
+    }): Promise<{
+        instanceId: string;
+        accessToken: string;
+        refreshToken: string;
+    }>;
+};
+/**
+ * Creates an authentication strategy for Wix Apps OAuth installation process.
+ * Use this authentication strategy when making requests to Wix APIs from your Wix App backend.
+ * @param opts Options for initializing the authentication strategy
+ * @param opts.appId The Wix App ID
+ * @param opts.appSecret The Wix App Secret
+ * @param opts.refreshToken An optional refresh token previously retrieved from Wix OAuth API
+ * @returns An authentication strategy that can be used with WixClient
+ * @example
+ * ```ts
+ * import { WixAppOAuthStrategy, createClient } from '@wix/sdk';
+ * import { products } from '@wix/stores';
+ *
+ * const client = createClient({
+ *  auth: WixAppOAuthStrategy({
+ *   appId: 'appId',
+ *   appSecret: 'appSecret',
+ *  }),
+ *  modules: { products },
+ * });
+ *
+ * const installUrl = client.auth.getInstallUrl({ redirectUrl: 'https://example.com' });
+ * // Redirect the user to the installUrl
+ *
+ * ...
+ *
+ * // in the callback handler of your http server
+ * // req.url is the url of the callback request
+ * const { instanceId, refreshToken } = await client.auth.handleOAuthCallback(req.url);
+ *
+ * // store the instanceId and refreshToken in your database
+ * // use the authorized client
+ * const products = await client.products.queryProducts().find();
+ *
+ * ```
+ */
+declare function WixAppOAuthStrategy(opts: {
+    appId: string;
+    appSecret: string;
+    refreshToken?: string;
+}): WixAppOAuthStrategy;
+
+export { API_URL, AccessToken, ApiKeyStrategy, AssertHostMatches, BuildDescriptors, CalculateNextState, Descriptors, IApiKeyStrategy, IOAuthStrategy, LoginParams, LoginState, OAuthStrategy, OauthData, OauthPKCE, ProcessableState, RefreshToken, RegisterParams, StateMachine, Token, TokenResponse, TokenRole, Tokens, WixAppOAuthStrategy, WixClient, createClient, decodeText, getDefaultDomain, media };

package/build/index.d.ts

@@ -7,6 +7,36 @@ import { authentication } from '@wix/identity';
 type PublicMetadata = {
     PACKAGE_NAME?: string;
 };
+declare const API_URL = "www.wixapis.com";
+
+declare const getDefaultDomain: (method: string, url: string) => "www.wixapis.com" | "readonly.wixapis.com";
+
+type RequestContext = {
+    isSSR: boolean;
+    host: string;
+    protocol?: string;
+};
+/**
+ * Ambassador request options types are copied mostly from AxiosRequestConfig.
+ * They are copied and not imported to reduce the amount of dependencies (to reduce install time).
+ * https://github.com/axios/axios/blob/3f53eb6960f05a1f88409c4b731a40de595cb825/index.d.ts#L307-L315
+ */
+type Method = 'get' | 'GET' | 'delete' | 'DELETE' | 'head' | 'HEAD' | 'options' | 'OPTIONS' | 'post' | 'POST' | 'put' | 'PUT' | 'patch' | 'PATCH' | 'purge' | 'PURGE' | 'link' | 'LINK' | 'unlink' | 'UNLINK';
+type ResponseTransformer = (data: any, headers?: any) => any;
+type AmbassadorRequestOptions<T = any> = {
+    _?: T;
+    url?: string;
+    method?: Method;
+    params?: any;
+    data?: any;
+    transformResponse?: ResponseTransformer | ResponseTransformer[];
+};
+type AmbassadorFactory<Request, Response> = {
+    (payload: Request): (context: RequestContext) => AmbassadorRequestOptions<Response>;
+    __isAmbassador: boolean;
+};
+type AmbassadorFunctionDescriptor<Request = any, Response = any> = AmbassadorFactory<Request, Response>;
+type BuildAmbassadorFunction<T extends AmbassadorFunctionDescriptor> = T extends AmbassadorFunctionDescriptor<infer Request, infer Response> ? (req: Request) => Promise<Response> : never;
 
 type Headers = {
     Authorization: string;
@@ -17,10 +47,13 @@ type Headers = {
  * Any non-descriptor properties are removed from the returned object, including descriptors that
  * do not match the given host (as they will not work with the given host).
  */
-type BuildDescriptors<T extends Descriptors, H extends Host<any> | undefined> = BuildRESTDescriptors<T> & (H extends Host<any> ? BuildHostDescriptors<T> : {});
+type BuildDescriptors<T extends Descriptors, H extends Host<any> | undefined> = BuildRESTDescriptors<T> & BuildAmbassadorDescriptors<T> & (H extends Host<any> ? BuildHostDescriptors<T> : {});
 type BuildRESTDescriptors<T extends Descriptors> = T extends RESTFunctionDescriptor ? BuildRESTFunction<T> : ConditionalExcept<{
     [Key in keyof T]: T[Key] extends Descriptors ? BuildRESTDescriptors<T[Key]> : never;
 }, EmptyObject>;
+type BuildAmbassadorDescriptors<T extends Descriptors> = T extends AmbassadorFunctionDescriptor ? BuildAmbassadorFunction<T> : ConditionalExcept<{
+    [Key in keyof T]: T[Key] extends Descriptors ? BuildAmbassadorDescriptors<T[Key]> : never;
+}, EmptyObject>;
 type BuildHostDescriptors<T extends Descriptors> = T extends HostModule<any, any> ? HostModuleAPI<T> : ConditionalExcept<{
     [Key in keyof T]: T[Key] extends Descriptors ? BuildHostDescriptors<T[Key]> : never;
 }, EmptyObject>;
@@ -29,7 +62,7 @@ type BuildHostDescriptors<T extends Descriptors> = T extends HostModule<any, any
  * can either be a REST module or a host module.
  * This type is recursive, so it can describe nested modules.
  */
-type Descriptors = RESTFunctionDescriptor | HostModule<any, any> | {
+type Descriptors = RESTFunctionDescriptor | AmbassadorFunctionDescriptor | HostModule<any, any> | {
     [key: string]: Descriptors | PublicMetadata | any;
 };
 /**
@@ -222,4 +255,58 @@ declare function ApiKeyStrategy({ siteId, accountId, apiKey, }: {
     apiKey: string;
 } & Context): IApiKeyStrategy;
 
-export { AccessToken, ApiKeyStrategy, AssertHostMatches, BuildDescriptors, CalculateNextState, Descriptors, IApiKeyStrategy, IOAuthStrategy, LoginParams, LoginState, OAuthStrategy, OauthData, OauthPKCE, ProcessableState, RefreshToken, RegisterParams, StateMachine, Token, TokenResponse, TokenRole, Tokens, WixClient, createClient, decodeText, media };
+type WixAppOAuthStrategy = AuthenticationStrategy & {
+    getInstallUrl({ redirectUrl }: {
+        redirectUrl: string;
+    }): string;
+    handleOAuthCallback(url: string, opts?: {
+        state: string;
+    }): Promise<{
+        instanceId: string;
+        accessToken: string;
+        refreshToken: string;
+    }>;
+};
+/**
+ * Creates an authentication strategy for Wix Apps OAuth installation process.
+ * Use this authentication strategy when making requests to Wix APIs from your Wix App backend.
+ * @param opts Options for initializing the authentication strategy
+ * @param opts.appId The Wix App ID
+ * @param opts.appSecret The Wix App Secret
+ * @param opts.refreshToken An optional refresh token previously retrieved from Wix OAuth API
+ * @returns An authentication strategy that can be used with WixClient
+ * @example
+ * ```ts
+ * import { WixAppOAuthStrategy, createClient } from '@wix/sdk';
+ * import { products } from '@wix/stores';
+ *
+ * const client = createClient({
+ *  auth: WixAppOAuthStrategy({
+ *   appId: 'appId',
+ *   appSecret: 'appSecret',
+ *  }),
+ *  modules: { products },
+ * });
+ *
+ * const installUrl = client.auth.getInstallUrl({ redirectUrl: 'https://example.com' });
+ * // Redirect the user to the installUrl
+ *
+ * ...
+ *
+ * // in the callback handler of your http server
+ * // req.url is the url of the callback request
+ * const { instanceId, refreshToken } = await client.auth.handleOAuthCallback(req.url);
+ *
+ * // store the instanceId and refreshToken in your database
+ * // use the authorized client
+ * const products = await client.products.queryProducts().find();
+ *
+ * ```
+ */
+declare function WixAppOAuthStrategy(opts: {
+    appId: string;
+    appSecret: string;
+    refreshToken?: string;
+}): WixAppOAuthStrategy;
+
+export { API_URL, AccessToken, ApiKeyStrategy, AssertHostMatches, BuildDescriptors, CalculateNextState, Descriptors, IApiKeyStrategy, IOAuthStrategy, LoginParams, LoginState, OAuthStrategy, OauthData, OauthPKCE, ProcessableState, RefreshToken, RegisterParams, StateMachine, Token, TokenResponse, TokenRole, Tokens, WixAppOAuthStrategy, WixClient, createClient, decodeText, getDefaultDomain, media };

package/build/index.js

@@ -31,16 +31,89 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  API_URL: () => API_URL,
   ApiKeyStrategy: () => ApiKeyStrategy,
   LoginState: () => LoginState,
   OAuthStrategy: () => OAuthStrategy,
   TokenRole: () => TokenRole,
+  WixAppOAuthStrategy: () => WixAppOAuthStrategy,
   createClient: () => createClient,
   decodeText: () => decodeText,
+  getDefaultDomain: () => getDefaultDomain,
   media: () => media
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/ambassador-modules.ts
+var import_velo = require("@wix/metro-runtime/velo");
+var parseMethod = (method) => {
+  switch (method) {
+    case "get":
+    case "GET":
+      return "GET";
+    case "post":
+    case "POST":
+      return "POST";
+    case "put":
+    case "PUT":
+      return "PUT";
+    case "delete":
+    case "DELETE":
+      return "DELETE";
+    case "patch":
+    case "PATCH":
+      return "PATCH";
+    case "head":
+    case "HEAD":
+      return "HEAD";
+    case "options":
+    case "OPTIONS":
+      return "OPTIONS";
+    default:
+      throw new Error(`Unknown method: ${method}`);
+  }
+};
+var toHTTPModule = (factory) => (httpClient) => async (payload) => {
+  let requestOptions;
+  const HTTPFactory = (context) => {
+    requestOptions = factory(payload)(context);
+    if (requestOptions.url === void 0) {
+      throw new Error(
+        "Url was not successfully created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const { method, url, params } = requestOptions;
+    return {
+      ...requestOptions,
+      method: parseMethod(method),
+      url,
+      data: requestOptions.data,
+      params
+    };
+  };
+  try {
+    const response = await httpClient.request(HTTPFactory);
+    if (requestOptions === void 0) {
+      throw new Error(
+        "Request options were not created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const transformations = Array.isArray(requestOptions.transformResponse) ? requestOptions.transformResponse : [requestOptions.transformResponse];
+    let data = response.data;
+    transformations.forEach((transform) => {
+      if (transform) {
+        data = transform(response.data, response.headers);
+      }
+    });
+    return data;
+  } catch (e) {
+    throw (0, import_velo.transformError)(e);
+  }
+};
+var ambassadorModuleOptions = () => ({
+  HTTPHost: self.location.host
+});
+
 // src/common.ts
 var PUBLIC_METADATA_KEY = "__metadata";
 var API_URL = "www.wixapis.com";
@@ -79,15 +152,16 @@ function objectToKeyValue(input) {
 }
 
 // src/rest-modules.ts
-function buildRESTDescriptor(origFunc, publicMetadata, boundFetch) {
+var getDefaultDomain = (method, url) => method === "GET" && !FORCE_WRITE_API_URLS.some((write_url) => url === write_url) ? READ_ONLY_API_URL : API_URL;
+function buildRESTDescriptor(origFunc, publicMetadata, boundFetch, options) {
   return origFunc({
     request: async (factory) => {
-      const requestOptions = factory({ host: API_URL });
+      const requestOptions = factory({ host: options?.HTTPHost || API_URL });
       let request = requestOptions;
       if (request.method === "GET" && request.fallback?.length && request.params.toString().length > 4e3) {
         request = requestOptions.fallback[0];
       }
-      const domain = request.method === "GET" && !FORCE_WRITE_API_URLS.some((url2) => request.url === url2) ? READ_ONLY_API_URL : API_URL;
+      const domain = options?.HTTPHost ?? getDefaultDomain(request.method, request.url);
       let url = `https://${domain}${request.url}`;
       if (request.params && request.params.toString()) {
         url += `?${request.params.toString()}`;
@@ -179,10 +253,15 @@ function createClient(config) {
     if (isHostModule(modules) && config.host) {
       return buildHostModule(modules, config.host);
     } else if (typeof modules === "function") {
+      const { module: module2, options } = modules.__isAmbassador ? {
+        module: toHTTPModule(modules),
+        options: ambassadorModuleOptions()
+      } : { module: modules, options: void 0 };
       return buildRESTDescriptor(
-        modules,
+        module2,
         metadata ?? {},
-        boundFetch
+        boundFetch,
+        options
       );
     } else if (isObject(modules)) {
       return Object.fromEntries(
@@ -779,16 +858,100 @@ function ApiKeyStrategy({
   };
 }
 
+// src/auth/WixAppOAuthStrategy.ts
+function WixAppOAuthStrategy(opts) {
+  let refreshToken = opts.refreshToken;
+  return {
+    getInstallUrl({ redirectUrl }) {
+      return `https://www.wix.com/installer/install?appId=${opts.appId}&redirectUrl=${redirectUrl}`;
+    },
+    async handleOAuthCallback(url, oauthOpts) {
+      const params = new URLSearchParams(new URL(url).search);
+      const state = params.get("state");
+      if (state && oauthOpts?.state && state !== oauthOpts.state) {
+        throw new Error(
+          `Invalid OAuth callback URL. Expected state to be "${oauthOpts.state}" but got "${state}"`
+        );
+      }
+      const code = params.get("code");
+      const instanceId = params.get("instanceId");
+      if (!code || !instanceId) {
+        throw new Error(
+          "Invalid OAuth callback URL. Make sure you pass the url including the code and instanceId query params."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          code,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "authorization_code"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange authorization code for refresh token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        instanceId,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token
+      };
+    },
+    async getAuthHeaders() {
+      if (!refreshToken) {
+        throw new Error(
+          "Missing refresh token. Either pass it to the WixAppOAuthStrategy or use the handleOAuthCallback method to retrieve it."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          refresh_token: refreshToken,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "refresh_token"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange refresh token for access token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        headers: {
+          Authorization: tokens.access_token
+        }
+      };
+    }
+  };
+}
+
 // src/index.ts
 __reExport(src_exports, require("@wix/sdk-types"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  API_URL,
   ApiKeyStrategy,
   LoginState,
   OAuthStrategy,
   TokenRole,
+  WixAppOAuthStrategy,
   createClient,
   decodeText,
+  getDefaultDomain,
   media,
   ...require("@wix/sdk-types")
 });

package/build/index.mjs

@@ -1,3 +1,73 @@
+// src/ambassador-modules.ts
+import { transformError } from "@wix/metro-runtime/velo";
+var parseMethod = (method) => {
+  switch (method) {
+    case "get":
+    case "GET":
+      return "GET";
+    case "post":
+    case "POST":
+      return "POST";
+    case "put":
+    case "PUT":
+      return "PUT";
+    case "delete":
+    case "DELETE":
+      return "DELETE";
+    case "patch":
+    case "PATCH":
+      return "PATCH";
+    case "head":
+    case "HEAD":
+      return "HEAD";
+    case "options":
+    case "OPTIONS":
+      return "OPTIONS";
+    default:
+      throw new Error(`Unknown method: ${method}`);
+  }
+};
+var toHTTPModule = (factory) => (httpClient) => async (payload) => {
+  let requestOptions;
+  const HTTPFactory = (context) => {
+    requestOptions = factory(payload)(context);
+    if (requestOptions.url === void 0) {
+      throw new Error(
+        "Url was not successfully created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const { method, url, params } = requestOptions;
+    return {
+      ...requestOptions,
+      method: parseMethod(method),
+      url,
+      data: requestOptions.data,
+      params
+    };
+  };
+  try {
+    const response = await httpClient.request(HTTPFactory);
+    if (requestOptions === void 0) {
+      throw new Error(
+        "Request options were not created for this request, please reach out to support channels for assistance."
+      );
+    }
+    const transformations = Array.isArray(requestOptions.transformResponse) ? requestOptions.transformResponse : [requestOptions.transformResponse];
+    let data = response.data;
+    transformations.forEach((transform) => {
+      if (transform) {
+        data = transform(response.data, response.headers);
+      }
+    });
+    return data;
+  } catch (e) {
+    throw transformError(e);
+  }
+};
+var ambassadorModuleOptions = () => ({
+  HTTPHost: self.location.host
+});
+
 // src/common.ts
 var PUBLIC_METADATA_KEY = "__metadata";
 var API_URL = "www.wixapis.com";
@@ -36,15 +106,16 @@ function objectToKeyValue(input) {
 }
 
 // src/rest-modules.ts
-function buildRESTDescriptor(origFunc, publicMetadata, boundFetch) {
+var getDefaultDomain = (method, url) => method === "GET" && !FORCE_WRITE_API_URLS.some((write_url) => url === write_url) ? READ_ONLY_API_URL : API_URL;
+function buildRESTDescriptor(origFunc, publicMetadata, boundFetch, options) {
   return origFunc({
     request: async (factory) => {
-      const requestOptions = factory({ host: API_URL });
+      const requestOptions = factory({ host: options?.HTTPHost || API_URL });
       let request = requestOptions;
       if (request.method === "GET" && request.fallback?.length && request.params.toString().length > 4e3) {
         request = requestOptions.fallback[0];
       }
-      const domain = request.method === "GET" && !FORCE_WRITE_API_URLS.some((url2) => request.url === url2) ? READ_ONLY_API_URL : API_URL;
+      const domain = options?.HTTPHost ?? getDefaultDomain(request.method, request.url);
       let url = `https://${domain}${request.url}`;
       if (request.params && request.params.toString()) {
         url += `?${request.params.toString()}`;
@@ -136,10 +207,15 @@ function createClient(config) {
     if (isHostModule(modules) && config.host) {
       return buildHostModule(modules, config.host);
     } else if (typeof modules === "function") {
+      const { module, options } = modules.__isAmbassador ? {
+        module: toHTTPModule(modules),
+        options: ambassadorModuleOptions()
+      } : { module: modules, options: void 0 };
       return buildRESTDescriptor(
-        modules,
+        module,
         metadata ?? {},
-        boundFetch
+        boundFetch,
+        options
       );
     } else if (isObject(modules)) {
       return Object.fromEntries(
@@ -736,14 +812,98 @@ function ApiKeyStrategy({
   };
 }
 
+// src/auth/WixAppOAuthStrategy.ts
+function WixAppOAuthStrategy(opts) {
+  let refreshToken = opts.refreshToken;
+  return {
+    getInstallUrl({ redirectUrl }) {
+      return `https://www.wix.com/installer/install?appId=${opts.appId}&redirectUrl=${redirectUrl}`;
+    },
+    async handleOAuthCallback(url, oauthOpts) {
+      const params = new URLSearchParams(new URL(url).search);
+      const state = params.get("state");
+      if (state && oauthOpts?.state && state !== oauthOpts.state) {
+        throw new Error(
+          `Invalid OAuth callback URL. Expected state to be "${oauthOpts.state}" but got "${state}"`
+        );
+      }
+      const code = params.get("code");
+      const instanceId = params.get("instanceId");
+      if (!code || !instanceId) {
+        throw new Error(
+          "Invalid OAuth callback URL. Make sure you pass the url including the code and instanceId query params."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          code,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "authorization_code"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange authorization code for refresh token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        instanceId,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token
+      };
+    },
+    async getAuthHeaders() {
+      if (!refreshToken) {
+        throw new Error(
+          "Missing refresh token. Either pass it to the WixAppOAuthStrategy or use the handleOAuthCallback method to retrieve it."
+        );
+      }
+      const tokensRes = await fetch("https://www.wixapis.com/oauth/access", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          refresh_token: refreshToken,
+          client_id: opts.appId,
+          client_secret: opts.appSecret,
+          grant_type: "refresh_token"
+        })
+      });
+      if (tokensRes.status !== 200) {
+        throw new Error(
+          `Failed to exchange refresh token for access token. Unexpected status code from Wix OAuth API: ${tokensRes.status}`
+        );
+      }
+      const tokens = await tokensRes.json();
+      refreshToken = tokens.refresh_token;
+      return {
+        headers: {
+          Authorization: tokens.access_token
+        }
+      };
+    }
+  };
+}
+
 // src/index.ts
 export * from "@wix/sdk-types";
 export {
+  API_URL,
   ApiKeyStrategy,
   LoginState,
   OAuthStrategy,
   TokenRole,
+  WixAppOAuthStrategy,
   createClient,
   decodeText,
+  getDefaultDomain,
   media
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/sdk",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "license": "UNLICENSED",
   "author": {
     "name": "Ronny Ringel",
@@ -30,28 +30,32 @@
     "*.{js,ts}": "yarn lint"
   },
   "dependencies": {
-    "@babel/runtime": "^7.22.11",
-    "@wix/identity": "^1.0.54",
-    "@wix/image-kit": "^1.36.0",
-    "@wix/redirects": "^1.0.23",
-    "@wix/sdk-types": "1.3.0",
+    "@babel/runtime": "^7.22.15",
+    "@wix/identity": "^1.0.57",
+    "@wix/image-kit": "^1.37.0",
+    "@wix/metro-runtime": "^1.1529.0",
+    "@wix/redirects": "^1.0.24",
+    "@wix/sdk-types": "1.4.0",
     "pkce-challenge": "^3.1.0",
     "querystring": "^0.2.1",
     "type-fest": "^3.13.1"
   },
   "devDependencies": {
-    "@swc/core": "^1.3.80",
+    "@swc/core": "^1.3.83",
     "@swc/jest": "^0.2.29",
     "@types/jest": "^27.5.2",
-    "@types/node": "^16.18.46",
-    "@wix/ecom": "^1.0.342",
-    "@wix/events": "^1.0.115",
-    "@wix/metro": "^1.0.65",
+    "@types/node": "^16.18.50",
+    "@types/node-fetch": "^2.6.4",
+    "@wix/ecom": "^1.0.351",
+    "@wix/events": "^1.0.117",
+    "@wix/metro": "^1.0.67",
     "eslint": "^7.32.0",
     "eslint-config-sdk": "0.0.0",
     "is-ci": "^3.0.1",
     "jest": "^27.5.1",
     "jest-teamcity": "^1.11.0",
+    "nock": "^13.3.3",
+    "node-fetch": "2.6.13",
     "ts-jest": "^27.1.5",
     "tsup": "^7.2.0",
     "typescript": "~4.9.5"
@@ -79,5 +83,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "2a6a54a97f2776cdbc13af01a1ac8a5a0b6c6522b2a4bbff0a80f8b6"
+  "falconPackageHash": "9b6b240d14e5fef75a1df39838bcd3c97317d7c97d86f43073bb4306"
 }