@progus/connector 0.5.4 → 0.6.0

package/README.md

@@ -37,6 +37,39 @@ await connector.trackSubscriptionUpdated({
 await connector.trackUninstall({ shopDomain: session.shop });
 ```
 
+## Prompt: Partner program implementation (copy/paste)
+
+```
+You are integrating Progus Partner Program using @progus/connector in a Shopify app.
+
+Implement these pieces:
+1) Server connector:
+   - createProgusConnector({ appKey, PARTNERS_API_URL, PARTNERS_SECRET_KEY, PARTNERS_API_KEY })
+   - expose getPartnersConnector() + isPartnersConnectorConfigured()
+
+2) Install tracking:
+   - after app install, call trackInstall({ shopDomain, partnerId })
+   - partnerId source: read cookie "progus_partner_id" on progus.com
+   - cookie must be JS-readable (HttpOnly=false) and cross-site (SameSite=None; Secure)
+   - if partnerId is missing, skip tracking
+
+3) Partner ID assignment UI:
+   - save partnerId from merchant input (Partner ID field)
+   - call assignPartnerId({ shopDomain, partnerId }) on save
+   - lock the field after successful save
+   - optionally check partnerId on load with checkPartnerId({ shopDomain })
+
+4) Subscription tracking:
+   - on app_subscriptions/update webhook, send trackSubscriptionUpdated
+   - payload must include: subscriptionId (digits), subscriptionPrice (number), subscriptionPeriod ("EVERY_30_DAYS" or "ANNUAL"), subscriptionStatus, subscriptionName
+   - if webhook payload is missing price/interval, fetch details via Admin GraphQL node(id) -> AppSubscription -> lineItems.plan.pricingDetails
+
+5) Uninstall tracking:
+   - on app/uninstalled webhook, call trackUninstall({ shopDomain })
+
+Return errors gracefully; do not break webhooks if partner tracking fails.
+```
+
 ## Partner ID assignment
 
 ```ts
@@ -58,9 +91,25 @@ import { signPayload } from "@progus/connector";
 const signature = signPayload(JSON.stringify({ test: true }), process.env.PARTNERS_SECRET_KEY!);
 ```
 
-## UI components and cross-sell
+## Cross-sell recommendations (server-side)
+
+Use the connector to fetch and filter the Progus apps catalog on the backend,
+then pass the list to your frontend UI.
+
+```ts
+import { getCrossSellOffersFromApi } from "@progus/connector";
+
+const recommendations = await getCrossSellOffersFromApi({
+  appName: "progus-store-locator",
+  limit: 3,
+  fetch, // pass your server-side fetch
+});
+```
+
+## UI components
 
-Use `@progus/connector-ui` for browser-safe helpers and UI components.
+Use `@progus/connector-ui` for UI components. It re-exports cross-sell helpers
+from `@progus/connector`.
 
 ## Environment variables
 

package/dist/index.cjs

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createProgusConnector: () => createProgusConnector,
+  fetchAppsCatalog: () => fetchAppsCatalog,
+  getCrossSellOffers: () => getCrossSellOffers,
+  getCrossSellOffersFromApi: () => getCrossSellOffersFromApi,
   normalizePartnerId: () => normalizePartnerId,
   signPayload: () => signPayload
 });
@@ -61,7 +64,19 @@ function createProgusConnector(config) {
   const enableIdempotency = config.enableIdempotency !== false;
   const validSubscriptionPeriods = /* @__PURE__ */ new Set(["ANNUAL", "EVERY_30_DAYS"]);
   if (!fetchImpl) {
-    throw new Error("Fetch implementation is required");
+    const message = "Fetch implementation is required";
+    logger?.error?.(message);
+    const fail = async () => ({ success: false, message });
+    return {
+      track: async () => ({ success: false, message }),
+      trackInstall: fail,
+      trackUninstall: fail,
+      trackSubscriptionPurchased: fail,
+      trackSubscriptionUpdated: fail,
+      trackSubscriptionCancelled: fail,
+      assignPartnerId: fail,
+      checkPartnerId: async () => ({ success: false, message, status: 500 })
+    };
   }
   async function postEvent(eventName, payload) {
     const { shopDomain, partnerId, data, externalId } = payload;
@@ -234,9 +249,111 @@ function createProgusConnector(config) {
     checkPartnerId
   };
 }
+
+// src/crossSell.ts
+function getCrossSellOffers(options = {}) {
+  const appsCatalog = options.appsCatalog ?? [];
+  const installedKeys = new Set(
+    [options.appName, ...options.installedAppKeys ?? []].filter(
+      (key) => Boolean(key)
+    )
+  );
+  const locale = options.locale;
+  return appsCatalog.filter((app) => app.enabled !== false).filter((app) => locale ? !app.locales || app.locales.includes(locale) : true).filter((app) => !installedKeys.has(app.key)).sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
+var DEFAULT_APPS_CATALOG_URL = "https://appsdata.progus.com/recommendations";
+var FALLBACK_APPS_CATALOG = [
+  {
+    key: "progus_ai_studio",
+    type: "app",
+    title: "Progus AI Studio",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Generate on-brand AI product & variant images in bulk.",
+    url: "https://apps.shopify.com/progus-ai-studio",
+    icon: "https://cdn.shopify.com/app-store/listing_images/9428a41ed53c66cd7329a2583cd2f3d9/icon/COje1rnS4pEDEAE=.png",
+    priority: 100,
+    enabled: true
+  },
+  {
+    key: "progus_trust_badges",
+    type: "app",
+    title: "Progus Trust Badges",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Add Trust Badges to your store to build trust and credibility.",
+    url: "https://apps.shopify.com/progus-trust-badges-1",
+    icon: "https://cdn.shopify.com/app-store/listing_images/f9d0009e237f27d2db35b41ef99be858/icon/CJ3y1qDn1JEDEAE=.png",
+    priority: 80,
+    enabled: true
+  },
+  {
+    key: "progus_cod",
+    type: "app",
+    title: "Progus COD",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Automate COD Fees & Hide/Show Cash on Delivery by Rules.",
+    url: "https://apps.shopify.com/progus-cod",
+    icon: "https://cdn.shopify.com/app-store/listing_images/bc537219cc3ed2bd4e7e3e683fe6b74a/icon/CMi_6dTEkIoDEAE=.png",
+    priority: 90,
+    enabled: true
+  }
+];
+function buildFallbackCatalog(options) {
+  const appName = options.appName;
+  const limit = typeof options.limit === "number" ? options.limit : 3;
+  let items = FALLBACK_APPS_CATALOG.filter((app) => app.enabled !== false);
+  if (appName) {
+    items = items.filter((app) => app.key !== appName);
+  }
+  if (limit > 0) {
+    items = items.slice(0, limit);
+  }
+  return items;
+}
+async function fetchAppsCatalog(options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const logger = options.logger ?? console;
+  const appName = options.appName;
+  const baseUrl = stripTrailingSlash(options.appsCatalogUrl ?? DEFAULT_APPS_CATALOG_URL);
+  const limit = typeof options.limit === "number" ? options.limit : 3;
+  const params = new URLSearchParams();
+  if (appName) params.set("appName", appName);
+  if (limit > 0) params.set("limit", String(limit));
+  const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+  if (!fetchImpl) {
+    logger?.error?.("Failed to fetch apps catalog", {
+      error: "Fetch implementation is required"
+    });
+    return buildFallbackCatalog(options);
+  }
+  try {
+    const response = await fetchImpl(url);
+    const text = await response.text();
+    const parsed = safeJsonParse(text);
+    if (!response.ok || !parsed) {
+      logger?.error?.("Failed to fetch apps catalog", { status: response.status });
+      return buildFallbackCatalog(options);
+    }
+    return parsed;
+  } catch (error) {
+    logger?.error?.("Failed to fetch apps catalog", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return buildFallbackCatalog(options);
+  }
+}
+async function getCrossSellOffersFromApi(options = {}) {
+  const appsCatalog = options.appsCatalog ?? await fetchAppsCatalog(options);
+  return getCrossSellOffers({ ...options, appsCatalog });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createProgusConnector,
+  fetchAppsCatalog,
+  getCrossSellOffers,
+  getCrossSellOffersFromApi,
   normalizePartnerId,
   signPayload
 });

package/dist/index.d.cts

@@ -44,6 +44,32 @@ type SubscriptionEventData = {
     subscriptionPrice?: number | string;
     subscriptionPeriod?: string;
 };
+type AppsCatalogEntry = {
+    key: string;
+    type: string;
+    title: string;
+    company?: string;
+    companyUrl?: string;
+    desc?: string;
+    url: string;
+    icon?: string;
+    enabled?: boolean;
+    priority?: number;
+    locales?: string[];
+};
+type CrossSellOptions = {
+    appName?: string;
+    installedAppKeys?: string[];
+    locale?: string;
+    shopPlan?: string;
+    appsCatalog?: AppsCatalogEntry[];
+};
+type CrossSellFetchOptions = CrossSellOptions & {
+    appsCatalogUrl?: string;
+    limit?: number;
+    fetch?: FetchLike;
+    logger?: Logger;
+};
 
 type Connector = {
     track: (eventName: TrackEventParams["eventName"], payload: Omit<TrackEventParams, "eventName">) => Promise<TrackResult>;
@@ -75,8 +101,12 @@ type Connector = {
 };
 declare function createProgusConnector(config: ConnectorConfig): Connector;
 
+declare function getCrossSellOffers(options?: CrossSellOptions): AppsCatalogEntry[];
+declare function fetchAppsCatalog(options?: CrossSellFetchOptions): Promise<AppsCatalogEntry[]>;
+declare function getCrossSellOffersFromApi(options?: CrossSellFetchOptions): Promise<AppsCatalogEntry[]>;
+
 declare function signPayload(body: string, secret: string): string;
 
 declare function normalizePartnerId(value?: string | null): string | null;
 
-export { type AssignPartnerIdInput, type CheckPartnerIdResult, type ConnectorConfig, type Logger, type SubscriptionEventData, type TrackEventName, type TrackEventParams, type TrackResult, createProgusConnector, normalizePartnerId, signPayload };
+export { type AppsCatalogEntry, type AssignPartnerIdInput, type CheckPartnerIdResult, type ConnectorConfig, type CrossSellFetchOptions, type CrossSellOptions, type Logger, type SubscriptionEventData, type TrackEventName, type TrackEventParams, type TrackResult, createProgusConnector, fetchAppsCatalog, getCrossSellOffers, getCrossSellOffersFromApi, normalizePartnerId, signPayload };

package/dist/index.d.ts

@@ -44,6 +44,32 @@ type SubscriptionEventData = {
     subscriptionPrice?: number | string;
     subscriptionPeriod?: string;
 };
+type AppsCatalogEntry = {
+    key: string;
+    type: string;
+    title: string;
+    company?: string;
+    companyUrl?: string;
+    desc?: string;
+    url: string;
+    icon?: string;
+    enabled?: boolean;
+    priority?: number;
+    locales?: string[];
+};
+type CrossSellOptions = {
+    appName?: string;
+    installedAppKeys?: string[];
+    locale?: string;
+    shopPlan?: string;
+    appsCatalog?: AppsCatalogEntry[];
+};
+type CrossSellFetchOptions = CrossSellOptions & {
+    appsCatalogUrl?: string;
+    limit?: number;
+    fetch?: FetchLike;
+    logger?: Logger;
+};
 
 type Connector = {
     track: (eventName: TrackEventParams["eventName"], payload: Omit<TrackEventParams, "eventName">) => Promise<TrackResult>;
@@ -75,8 +101,12 @@ type Connector = {
 };
 declare function createProgusConnector(config: ConnectorConfig): Connector;
 
+declare function getCrossSellOffers(options?: CrossSellOptions): AppsCatalogEntry[];
+declare function fetchAppsCatalog(options?: CrossSellFetchOptions): Promise<AppsCatalogEntry[]>;
+declare function getCrossSellOffersFromApi(options?: CrossSellFetchOptions): Promise<AppsCatalogEntry[]>;
+
 declare function signPayload(body: string, secret: string): string;
 
 declare function normalizePartnerId(value?: string | null): string | null;
 
-export { type AssignPartnerIdInput, type CheckPartnerIdResult, type ConnectorConfig, type Logger, type SubscriptionEventData, type TrackEventName, type TrackEventParams, type TrackResult, createProgusConnector, normalizePartnerId, signPayload };
+export { type AppsCatalogEntry, type AssignPartnerIdInput, type CheckPartnerIdResult, type ConnectorConfig, type CrossSellFetchOptions, type CrossSellOptions, type Logger, type SubscriptionEventData, type TrackEventName, type TrackEventParams, type TrackResult, createProgusConnector, fetchAppsCatalog, getCrossSellOffers, getCrossSellOffersFromApi, normalizePartnerId, signPayload };

package/dist/index.js

@@ -33,7 +33,19 @@ function createProgusConnector(config) {
   const enableIdempotency = config.enableIdempotency !== false;
   const validSubscriptionPeriods = /* @__PURE__ */ new Set(["ANNUAL", "EVERY_30_DAYS"]);
   if (!fetchImpl) {
-    throw new Error("Fetch implementation is required");
+    const message = "Fetch implementation is required";
+    logger?.error?.(message);
+    const fail = async () => ({ success: false, message });
+    return {
+      track: async () => ({ success: false, message }),
+      trackInstall: fail,
+      trackUninstall: fail,
+      trackSubscriptionPurchased: fail,
+      trackSubscriptionUpdated: fail,
+      trackSubscriptionCancelled: fail,
+      assignPartnerId: fail,
+      checkPartnerId: async () => ({ success: false, message, status: 500 })
+    };
   }
   async function postEvent(eventName, payload) {
     const { shopDomain, partnerId, data, externalId } = payload;
@@ -206,8 +218,110 @@ function createProgusConnector(config) {
     checkPartnerId
   };
 }
+
+// src/crossSell.ts
+function getCrossSellOffers(options = {}) {
+  const appsCatalog = options.appsCatalog ?? [];
+  const installedKeys = new Set(
+    [options.appName, ...options.installedAppKeys ?? []].filter(
+      (key) => Boolean(key)
+    )
+  );
+  const locale = options.locale;
+  return appsCatalog.filter((app) => app.enabled !== false).filter((app) => locale ? !app.locales || app.locales.includes(locale) : true).filter((app) => !installedKeys.has(app.key)).sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
+var DEFAULT_APPS_CATALOG_URL = "https://appsdata.progus.com/recommendations";
+var FALLBACK_APPS_CATALOG = [
+  {
+    key: "progus_ai_studio",
+    type: "app",
+    title: "Progus AI Studio",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Generate on-brand AI product & variant images in bulk.",
+    url: "https://apps.shopify.com/progus-ai-studio",
+    icon: "https://cdn.shopify.com/app-store/listing_images/9428a41ed53c66cd7329a2583cd2f3d9/icon/COje1rnS4pEDEAE=.png",
+    priority: 100,
+    enabled: true
+  },
+  {
+    key: "progus_trust_badges",
+    type: "app",
+    title: "Progus Trust Badges",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Add Trust Badges to your store to build trust and credibility.",
+    url: "https://apps.shopify.com/progus-trust-badges-1",
+    icon: "https://cdn.shopify.com/app-store/listing_images/f9d0009e237f27d2db35b41ef99be858/icon/CJ3y1qDn1JEDEAE=.png",
+    priority: 80,
+    enabled: true
+  },
+  {
+    key: "progus_cod",
+    type: "app",
+    title: "Progus COD",
+    company: "Progus",
+    companyUrl: "https://progus.com",
+    desc: "Automate COD Fees & Hide/Show Cash on Delivery by Rules.",
+    url: "https://apps.shopify.com/progus-cod",
+    icon: "https://cdn.shopify.com/app-store/listing_images/bc537219cc3ed2bd4e7e3e683fe6b74a/icon/CMi_6dTEkIoDEAE=.png",
+    priority: 90,
+    enabled: true
+  }
+];
+function buildFallbackCatalog(options) {
+  const appName = options.appName;
+  const limit = typeof options.limit === "number" ? options.limit : 3;
+  let items = FALLBACK_APPS_CATALOG.filter((app) => app.enabled !== false);
+  if (appName) {
+    items = items.filter((app) => app.key !== appName);
+  }
+  if (limit > 0) {
+    items = items.slice(0, limit);
+  }
+  return items;
+}
+async function fetchAppsCatalog(options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const logger = options.logger ?? console;
+  const appName = options.appName;
+  const baseUrl = stripTrailingSlash(options.appsCatalogUrl ?? DEFAULT_APPS_CATALOG_URL);
+  const limit = typeof options.limit === "number" ? options.limit : 3;
+  const params = new URLSearchParams();
+  if (appName) params.set("appName", appName);
+  if (limit > 0) params.set("limit", String(limit));
+  const url = params.toString() ? `${baseUrl}?${params.toString()}` : baseUrl;
+  if (!fetchImpl) {
+    logger?.error?.("Failed to fetch apps catalog", {
+      error: "Fetch implementation is required"
+    });
+    return buildFallbackCatalog(options);
+  }
+  try {
+    const response = await fetchImpl(url);
+    const text = await response.text();
+    const parsed = safeJsonParse(text);
+    if (!response.ok || !parsed) {
+      logger?.error?.("Failed to fetch apps catalog", { status: response.status });
+      return buildFallbackCatalog(options);
+    }
+    return parsed;
+  } catch (error) {
+    logger?.error?.("Failed to fetch apps catalog", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return buildFallbackCatalog(options);
+  }
+}
+async function getCrossSellOffersFromApi(options = {}) {
+  const appsCatalog = options.appsCatalog ?? await fetchAppsCatalog(options);
+  return getCrossSellOffers({ ...options, appsCatalog });
+}
 export {
   createProgusConnector,
+  fetchAppsCatalog,
+  getCrossSellOffers,
+  getCrossSellOffersFromApi,
   normalizePartnerId,
   signPayload
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progus/connector",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Progus partner/affiliate connector helpers",
   "license": "MIT",
   "type": "module",