retainful-shopify-sdk 1.0.2

package/README.md

@@ -0,0 +1,443 @@
+# @yuko-app/retainful-shopify-sdk
+
+A typed TypeScript SDK for sending Shopify app lifecycle events to [Retainful](https://retainful.com).  
+Built to be shared across all Yuko Apps — configure once per app, use everywhere.
+
+---
+
+## Installation
+
+```bash
+npm install @yuko-app/retainful-shopify-sdk
+```
+
+Or, if using a monorepo with a local path:
+
+```json
+// package.json of your Shopify app
+{
+  "dependencies": {
+    "@yuko-app/retainful-shopify-sdk": "file:../../packages/retainful-sdk"
+  }
+}
+```
+
+---
+
+## Setup
+
+### 1. Get your credentials from Retainful
+
+| Credential | Where to find it |
+|---|---|
+| `apiKey` | Retainful Dashboard → Settings → API Keys |
+
+### 2. Instantiate the client
+
+Create **one client per Shopify app** and export it for reuse.
+
+```typescript
+// lib/retainful.ts
+import { RetainfulClient } from "@yuko-app/retainful-shopify-sdk";
+
+export const retainful = new RetainfulClient(
+  {
+    apiKey: process.env.RETAINFUL_API_KEY!,
+  },
+  {
+    // Set these once — they're stamped on every event automatically
+    appName: "Order Tracking Pro",
+    appSlug: "order-tracking-pro",
+  }
+);
+```
+
+> **One client per app.** The `appName` and `appSlug` are baked into the client,
+> so you never repeat them at the call site.
+
+---
+
+## Usage
+
+### Track an Install
+
+Call this inside your Shopify auth callback or `app/installed` webhook handler.
+
+```typescript
+import { retainful } from "~/lib/retainful";
+
+// Inside your install handler
+await retainful.events.installed({
+  email: shop.email,
+  shopDomain: shop.myshopify_domain,    // e.g. "my-store.myshopify.com"
+  shopDetails: {
+    name: shop.name,
+    ownerName: shop.shop_owner,
+    plan: shop.plan_name,
+    country: shop.country_name,
+    currency: shop.currency,
+    timezone: shop.timezone,
+    phone: shop.phone,
+  },
+});
+```
+
+### Track an Uninstall
+
+Call this inside your `app/uninstalled` webhook handler.
+
+```typescript
+import { retainful } from "~/lib/retainful";
+
+// Inside your uninstall webhook handler
+await retainful.events.uninstalled({
+  email: shop.email,
+  shopDomain: shop.myshopify_domain,
+  shopDetails: {
+    name: shop.name,
+    ownerName: shop.shop_owner,
+    plan: shop.plan_name,
+    country: shop.country_name,
+    currency: shop.currency,
+    timezone: shop.timezone,
+  },
+});
+```
+
+---
+
+## Framework Setup
+
+The SDK is framework-agnostic — it only needs a place to instantiate the client once
+and a place to call `events.installed()` / `events.uninstalled()` (usually a webhook
+or auth callback). Below are idiomatic wirings for the common stacks.
+
+> In every example, set `RETAINFUL_API_KEY` in your environment and **never throw**
+> on a Retainful failure — a tracking error should not break your webhook response.
+
+### Remix
+
+```typescript
+// app/lib/retainful.ts
+import { RetainfulClient } from "@yuko-app/retainful-shopify-sdk";
+
+export const retainful = new RetainfulClient(
+  { apiKey: process.env.RETAINFUL_API_KEY! },
+  { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+);
+```
+
+```typescript
+// app/routes/webhooks.tsx
+import type { ActionFunctionArgs } from "@remix-run/node";
+import { retainful } from "~/lib/retainful";
+import { RetainfulApiError } from "@yuko-app/retainful-shopify-sdk";
+
+export const action = async ({ request }: ActionFunctionArgs) => {
+  const topic = request.headers.get("x-shopify-topic");
+  const shop = await request.json();
+
+  try {
+    if (topic === "app/uninstalled") {
+      await retainful.events.uninstalled({
+        email: shop.email,
+        shopDomain: shop.myshopify_domain,
+        shopDetails: {
+          name: shop.name,
+          ownerName: shop.shop_owner,
+          plan: shop.plan_name,
+          country: shop.country_name,
+          currency: shop.currency,
+        },
+      });
+    }
+  } catch (error) {
+    if (error instanceof RetainfulApiError) {
+      console.error(`Retainful error ${error.statusCode}:`, error.statusText);
+      // Don't throw — don't let Retainful failures break your webhook response
+    }
+  }
+
+  return new Response("OK", { status: 200 });
+};
+```
+
+### Next.js (App Router)
+
+```typescript
+// lib/retainful.ts
+import { RetainfulClient } from "@yuko-app/retainful-shopify-sdk";
+
+export const retainful = new RetainfulClient(
+  { apiKey: process.env.RETAINFUL_API_KEY! },
+  { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+);
+```
+
+```typescript
+// app/api/webhooks/route.ts
+import { NextResponse } from "next/server";
+import { retainful } from "@/lib/retainful";
+import { RetainfulApiError } from "@yuko-app/retainful-shopify-sdk";
+
+// Webhooks must run on the Node.js runtime, not the Edge runtime.
+export const runtime = "nodejs";
+
+export async function POST(request: Request) {
+  const topic = request.headers.get("x-shopify-topic");
+  const shop = await request.json();
+
+  try {
+    if (topic === "app/uninstalled") {
+      await retainful.events.uninstalled({
+        email: shop.email,
+        shopDomain: shop.myshopify_domain,
+        shopDetails: {
+          name: shop.name,
+          ownerName: shop.shop_owner,
+          plan: shop.plan_name,
+          country: shop.country_name,
+          currency: shop.currency,
+        },
+      });
+    }
+  } catch (error) {
+    if (error instanceof RetainfulApiError) {
+      console.error(`Retainful error ${error.statusCode}:`, error.statusText);
+    }
+  }
+
+  return NextResponse.json({ ok: true });
+}
+```
+
+> **Pages Router?** The same `retainful` client works inside
+> `pages/api/webhooks.ts` — read `req.headers["x-shopify-topic"]` and `req.body`,
+> then `res.status(200).json({ ok: true })`.
+
+### NestJS
+
+Wrap the client in an injectable provider so it can be shared across the app via DI.
+
+```typescript
+// retainful/retainful.module.ts
+import { Module } from "@nestjs/common";
+import { RetainfulClient } from "@yuko-app/retainful-shopify-sdk";
+
+export const RETAINFUL = "RETAINFUL_CLIENT";
+
+@Module({
+  providers: [
+    {
+      provide: RETAINFUL,
+      useFactory: () =>
+        new RetainfulClient(
+          { apiKey: process.env.RETAINFUL_API_KEY! },
+          { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+        ),
+    },
+  ],
+  exports: [RETAINFUL],
+})
+export class RetainfulModule {}
+```
+
+```typescript
+// webhooks/webhooks.controller.ts
+import { Controller, Post, Body, Headers, Inject } from "@nestjs/common";
+import { RetainfulClient, RetainfulApiError } from "@yuko-app/retainful-shopify-sdk";
+import { RETAINFUL } from "../retainful/retainful.module";
+
+@Controller("webhooks")
+export class WebhooksController {
+  constructor(@Inject(RETAINFUL) private readonly retainful: RetainfulClient) {}
+
+  @Post()
+  async handle(
+    @Headers("x-shopify-topic") topic: string,
+    @Body() shop: any
+  ) {
+    try {
+      if (topic === "app/uninstalled") {
+        await this.retainful.events.uninstalled({
+          email: shop.email,
+          shopDomain: shop.myshopify_domain,
+          shopDetails: {
+            name: shop.name,
+            ownerName: shop.shop_owner,
+            plan: shop.plan_name,
+            country: shop.country_name,
+            currency: shop.currency,
+          },
+        });
+      }
+    } catch (error) {
+      if (error instanceof RetainfulApiError) {
+        console.error(`Retainful error ${error.statusCode}:`, error.statusText);
+      }
+    }
+
+    return { ok: true };
+  }
+}
+```
+
+---
+
+## Retry Configuration
+
+By default the SDK retries failed requests (status codes `429`, `503`, `504`) up to **3 times** with exponential backoff.
+
+You can override this:
+
+```typescript
+const retainful = new RetainfulClient(
+  { apiKey: "..." },
+  { appName: "My App", appSlug: "my-app" },
+  {
+    retryCodes: [429, 503],
+    numRetries: 5,
+    maxInterval: 30, // seconds
+  }
+);
+```
+
+---
+
+## Payload Reference
+
+### `installed(payload)` / `uninstalled(payload)`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `email` | `string` | ✅ | Store owner email — contact identifier in Retainful |
+| `shopDomain` | `string` | ✅ | Myshopify domain, e.g. `my-store.myshopify.com` |
+| `shopDetails` | `ShopDetails` | ✅ | Full shop object from Shopify |
+
+### `ShopDetails`
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Store display name |
+| `ownerName` | `string` | Store owner's full name |
+| `plan` | `string` | Shopify plan, e.g. `"basic"`, `"shopify"`, `"advanced"` |
+| `country` | `string` | Store country |
+| `currency` | `string` | Store currency, e.g. `"USD"` |
+| `timezone` | `string` | Store timezone |
+| `phone` | `string \| null` | Owner phone number |
+
+All `ShopDetails` fields are optional. You can also pass any extra Shopify fields — the type allows `[key: string]: unknown`.
+
+---
+
+## What gets sent over the wire
+
+Every event POST to `https://api.retainful.net/api/v1/events` includes:
+
+**Headers:**
+```
+Retainful-Api-Key: YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:** the SDK maps the ergonomic `installed()` / `uninstalled()` payload onto
+Retainful's `eventName` / `contact` / `eventData` / `uniqueIdentifier` format:
+
+```json
+{
+  "eventName": "Order Tracking Pro installed",
+  "description": "App installed",
+  "contact": {
+    "email": "owner@my-store.com",
+    "first_name": "Jane",
+    "last_name": "Doe",
+    "phone": "+1234567890",
+    "email_opt_in": "SUBSCRIBED"
+  },
+  "eventData": {
+    "eventType": "installed",
+    "appName": "Order Tracking Pro",
+    "appSlug": "order-tracking-pro",
+    "storeDomain": "my-store.myshopify.com",
+    "countryCode": "United States",
+    "name": "My Store",
+    "plan": "basic",
+    "currency": "USD",
+    "timezone": "America/New_York"
+  },
+  "uniqueIdentifier": "my-store.myshopify.com-installed"
+}
+```
+
+**Mapping rules:**
+
+| Wire field | Source |
+|---|---|
+| `eventName` | `"<appName> installed"` / `"<appName> uninstalled"` |
+| `contact.email` | `payload.email` |
+| `contact.first_name` / `last_name` | split from `shopDetails.ownerName` (override with `firstName` / `lastName`) |
+| `contact.email_opt_in` | `payload.emailOptIn`, default `"SUBSCRIBED"` |
+| `eventData` | `eventType`, `appName`, `appSlug`, `storeDomain`, `countryCode` + all other `shopDetails` + any `payload.eventData` |
+| `uniqueIdentifier` | `payload.uniqueIdentifier`, default `"<shopDomain>-<installed\|uninstalled>"` |
+
+Need full control? Use the escape hatch — `retainful.events.track(rawEvent)` posts an
+`{ eventName, description, contact, eventData, uniqueIdentifier }` body verbatim with no mapping.
+
+---
+
+## Error Handling
+
+```typescript
+import { RetainfulApiError, RetainfulConfigError } from "@yuko-app/retainful-shopify-sdk";
+
+try {
+  await retainful.events.installed({ ... });
+} catch (error) {
+  if (error instanceof RetainfulApiError) {
+    console.error(error.statusCode);    // e.g. 401, 403, 422
+    console.error(error.statusText);    // e.g. "Unauthorized"
+    console.error(error.responseData);  // Full response body
+  }
+
+  if (error instanceof RetainfulConfigError) {
+    // Thrown at construction time if apiKey is missing
+    console.error(error.message);
+  }
+}
+```
+
+---
+
+## Multiple Apps (Monorepo)
+
+Each Shopify app creates its own client with its own `appName` / `appSlug`.  
+They all share the **same Retainful credentials** (scoped to Yuko Apps org via the API key).
+
+```typescript
+// apps/order-tracking/lib/retainful.ts
+export const retainful = new RetainfulClient(
+  { apiKey: process.env.RETAINFUL_API_KEY! },
+  { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+);
+
+// apps/reviews/lib/retainful.ts
+export const retainful = new RetainfulClient(
+  { apiKey: process.env.RETAINFUL_API_KEY! },
+  { appName: "Reviews & Ratings", appSlug: "reviews-ratings" }
+);
+```
+
+---
+
+## Building
+
+```bash
+npm run build   # compiles to /dist
+npm run dev     # watch mode
+```
+# Retainful-Shopify-apps-sdk-beta
+# Retainful-Shopify-apps-sdk
+# Retainful-Shopify-apps-sdk
+# Retainful-Shopify-apps-sdk
+# Retainful-Shopify-apps-sdk
+# Retainful-Shopify-apps-sdk

package/dist/api/events.d.ts

@@ -0,0 +1,45 @@
+import { RetainfulSession } from "../session";
+import { AppEventPayload, RetainfulEventRequest, RetainfulEventResponse, ShopifyAppConfig } from "../types/index";
+/**
+ * EventsApi
+ *
+ * Sends Shopify app lifecycle events (install / uninstall) to Retainful.
+ * Automatically injects app_name and app_slug from the ShopifyAppConfig
+ * so you never have to repeat them at the call site.
+ *
+ * @example
+ * const events = new EventsApi(session, { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" });
+ * await events.installed({ email, shopDomain, shopDetails });
+ * await events.uninstalled({ email, shopDomain, shopDetails });
+ */
+export declare class EventsApi {
+    private readonly session;
+    private readonly appConfig;
+    constructor(session: RetainfulSession, appConfig: ShopifyAppConfig);
+    /**
+     * Track an app install event.
+     * Call this in your Shopify app's install webhook or auth callback.
+     */
+    installed(payload: Omit<AppEventPayload, "eventType">): Promise<RetainfulEventResponse>;
+    /**
+     * Track an app uninstall event.
+     * Call this in your Shopify app/uninstalled webhook handler.
+     */
+    uninstalled(payload: Omit<AppEventPayload, "eventType">): Promise<RetainfulEventResponse>;
+    /**
+     * Send any lifecycle event directly (lower-level).
+     * Use installed() / uninstalled() for most cases.
+     *
+     * Maps the ergonomic SDK payload onto Retainful's wire format
+     * (eventName / contact / eventData / uniqueIdentifier).
+     */
+    sendEvent(payload: AppEventPayload): Promise<RetainfulEventResponse>;
+    /**
+     * Send a fully-formed event to Retainful with no mapping.
+     * Escape hatch for events that don't fit the install/uninstall shape.
+     */
+    track(event: RetainfulEventRequest): Promise<RetainfulEventResponse>;
+    /** Translate an AppEventPayload into the Retainful wire format. */
+    private buildEvent;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/api/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/api/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB;IAKlE;;;OAGG;IACG,SAAS,CACb,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAC1C,OAAO,CAAC,sBAAsB,CAAC;IAIlC;;;OAGG;IACG,WAAW,CACf,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAC1C,OAAO,CAAC,sBAAsB,CAAC;IAIlC;;;;;;OAMG;IACG,SAAS,CACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,sBAAsB,CAAC;IAIlC;;;OAGG;IACG,KAAK,CACT,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;IAOlC,mEAAmE;IACnE,OAAO,CAAC,UAAU;CAsCnB"}

package/dist/api/events.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsApi = void 0;
+const EVENTS_ENDPOINT = "/api/v1/events";
+/**
+ * EventsApi
+ *
+ * Sends Shopify app lifecycle events (install / uninstall) to Retainful.
+ * Automatically injects app_name and app_slug from the ShopifyAppConfig
+ * so you never have to repeat them at the call site.
+ *
+ * @example
+ * const events = new EventsApi(session, { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" });
+ * await events.installed({ email, shopDomain, shopDetails });
+ * await events.uninstalled({ email, shopDomain, shopDetails });
+ */
+class EventsApi {
+    constructor(session, appConfig) {
+        this.session = session;
+        this.appConfig = appConfig;
+    }
+    /**
+     * Track an app install event.
+     * Call this in your Shopify app's install webhook or auth callback.
+     */
+    async installed(payload) {
+        return this.sendEvent({ ...payload, eventType: "app/installed" });
+    }
+    /**
+     * Track an app uninstall event.
+     * Call this in your Shopify app/uninstalled webhook handler.
+     */
+    async uninstalled(payload) {
+        return this.sendEvent({ ...payload, eventType: "app/uninstalled" });
+    }
+    /**
+     * Send any lifecycle event directly (lower-level).
+     * Use installed() / uninstalled() for most cases.
+     *
+     * Maps the ergonomic SDK payload onto Retainful's wire format
+     * (eventName / contact / eventData / uniqueIdentifier).
+     */
+    async sendEvent(payload) {
+        return this.track(this.buildEvent(payload));
+    }
+    /**
+     * Send a fully-formed event to Retainful with no mapping.
+     * Escape hatch for events that don't fit the install/uninstall shape.
+     */
+    async track(event) {
+        return this.session.post(EVENTS_ENDPOINT, event);
+    }
+    /** Translate an AppEventPayload into the Retainful wire format. */
+    buildEvent(payload) {
+        var _a, _b, _c, _d, _e;
+        // "app/installed" -> "installed", "app/uninstalled" -> "uninstalled"
+        const shortType = payload.eventType.replace(/^app\//, "");
+        const { ownerName, phone, country, ...restDetails } = payload.shopDetails;
+        const nameTokens = (ownerName !== null && ownerName !== void 0 ? ownerName : "").trim().split(/\s+/).filter(Boolean);
+        const firstName = (_a = payload.firstName) !== null && _a !== void 0 ? _a : nameTokens[0];
+        const lastName = (_b = payload.lastName) !== null && _b !== void 0 ? _b : (nameTokens.slice(1).join(" ") || undefined);
+        return {
+            eventName: `${this.appConfig.appName} ${shortType}`,
+            description: (_c = payload.description) !== null && _c !== void 0 ? _c : `App ${shortType}`,
+            contact: {
+                email: payload.email,
+                first_name: firstName,
+                last_name: lastName,
+                phone: phone !== null && phone !== void 0 ? phone : undefined,
+                email_opt_in: (_d = payload.emailOptIn) !== null && _d !== void 0 ? _d : "SUBSCRIBED",
+            },
+            eventData: {
+                eventType: shortType,
+                appName: this.appConfig.appName,
+                appSlug: this.appConfig.appSlug,
+                storeDomain: payload.shopDomain,
+                countryCode: country,
+                ...restDetails,
+                ...payload.eventData,
+            },
+            uniqueIdentifier: (_e = payload.uniqueIdentifier) !== null && _e !== void 0 ? _e : `${payload.shopDomain}-${shortType}`,
+        };
+    }
+}
+exports.EventsApi = EventsApi;
+//# sourceMappingURL=events.js.map

package/dist/api/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/api/events.ts"],"names":[],"mappings":";;;AAQA,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAa,SAAS;IAIpB,YAAY,OAAyB,EAAE,SAA2B;QAChE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CACb,OAA2C;QAE3C,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CACf,OAA2C;QAE3C,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CACb,OAAwB;QAExB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CACT,KAA4B;QAE5B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,eAAe,EACf,KAAK,CACN,CAAC;IACJ,CAAC;IAED,mEAAmE;IAC3D,UAAU,CAAC,OAAwB;;QACzC,qEAAqE;QACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAE1D,MAAM,EACJ,SAAS,EACT,KAAK,EACL,OAAO,EACP,GAAG,WAAW,EACf,GAAG,OAAO,CAAC,WAAW,CAAC;QAExB,MAAM,UAAU,GAAG,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzE,MAAM,SAAS,GAAG,MAAA,OAAO,CAAC,SAAS,mCAAI,UAAU,CAAC,CAAC,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,QAAQ,mCAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC;QAElF,OAAO;YACL,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,SAAS,EAAE;YACnD,WAAW,EAAE,MAAA,OAAO,CAAC,WAAW,mCAAI,OAAO,SAAS,EAAE;YACtD,OAAO,EAAE;gBACP,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU,EAAE,SAAS;gBACrB,SAAS,EAAE,QAAQ;gBACnB,KAAK,EAAE,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,SAAS;gBACzB,YAAY,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,YAAY;aACjD;YACD,SAAS,EAAE;gBACT,SAAS,EAAE,SAAS;gBACpB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO;gBAC/B,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO;gBAC/B,WAAW,EAAE,OAAO,CAAC,UAAU;gBAC/B,WAAW,EAAE,OAAO;gBACpB,GAAG,WAAW;gBACd,GAAG,OAAO,CAAC,SAAS;aACrB;YACD,gBAAgB,EACd,MAAA,OAAO,CAAC,gBAAgB,mCAAI,GAAG,OAAO,CAAC,UAAU,IAAI,SAAS,EAAE;SACnE,CAAC;IACJ,CAAC;CACF;AA9FD,8BA8FC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { EventsApi } from "./api/events";
+import { RetainfulSessionConfig, ShopifyAppConfig, RetryConfig } from "./types/index";
+export { RetainfulApiError, RetainfulConfigError } from "./types/index";
+export type { RetainfulSessionConfig, ShopifyAppConfig, RetryConfig, AppEventPayload, ShopDetails, RetainfulEventType, RetainfulEventResponse, RetainfulEventRequest, RetainfulContact, EmailOptInStatus, } from "./types/index";
+/**
+ * RetainfulClient
+ *
+ * The main entry point for the Retainful SDK.
+ * Instantiate once per Shopify app and reuse across your request handlers.
+ *
+ * @example
+ * import { RetainfulClient } from "@akashm-cartrabbit/retainful-shopify-sdk";
+ *
+ * const retainful = new RetainfulClient(
+ *   { apiKey: process.env.RETAINFUL_API_KEY },
+ *   { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+ * );
+ *
+ * // On install:
+ * await retainful.events.installed({ email, shopDomain, shopDetails });
+ *
+ * // On uninstall:
+ * await retainful.events.uninstalled({ email, shopDomain, shopDetails });
+ */
+export declare class RetainfulClient {
+    readonly events: EventsApi;
+    private readonly session;
+    constructor(sessionConfig: RetainfulSessionConfig, appConfig: ShopifyAppConfig, retryConfig?: RetryConfig);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAe;IAC1B,SAAgB,MAAM,EAAE,SAAS,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAGzC,aAAa,EAAE,sBAAsB,EACrC,SAAS,EAAE,gBAAgB,EAC3B,WAAW,CAAC,EAAE,WAAW;CAK5B"}

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetainfulClient = exports.RetainfulConfigError = exports.RetainfulApiError = void 0;
+const session_1 = require("./session");
+const events_1 = require("./api/events");
+var index_1 = require("./types/index");
+Object.defineProperty(exports, "RetainfulApiError", { enumerable: true, get: function () { return index_1.RetainfulApiError; } });
+Object.defineProperty(exports, "RetainfulConfigError", { enumerable: true, get: function () { return index_1.RetainfulConfigError; } });
+/**
+ * RetainfulClient
+ *
+ * The main entry point for the Retainful SDK.
+ * Instantiate once per Shopify app and reuse across your request handlers.
+ *
+ * @example
+ * import { RetainfulClient } from "@akashm-cartrabbit/retainful-shopify-sdk";
+ *
+ * const retainful = new RetainfulClient(
+ *   { apiKey: process.env.RETAINFUL_API_KEY },
+ *   { appName: "Order Tracking Pro", appSlug: "order-tracking-pro" }
+ * );
+ *
+ * // On install:
+ * await retainful.events.installed({ email, shopDomain, shopDetails });
+ *
+ * // On uninstall:
+ * await retainful.events.uninstalled({ email, shopDomain, shopDetails });
+ */
+class RetainfulClient {
+    constructor(sessionConfig, appConfig, retryConfig) {
+        this.session = new session_1.RetainfulSession(sessionConfig, retryConfig);
+        this.events = new events_1.EventsApi(this.session, appConfig);
+    }
+}
+exports.RetainfulClient = RetainfulClient;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAA6C;AAC7C,yCAAyC;AAOzC,uCAAwE;AAA/D,0GAAA,iBAAiB,OAAA;AAAE,6GAAA,oBAAoB,OAAA;AAchD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,eAAe;IAI1B,YACE,aAAqC,EACrC,SAA2B,EAC3B,WAAyB;QAEzB,IAAI,CAAC,OAAO,GAAG,IAAI,0BAAgB,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAS,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;CACF;AAZD,0CAYC"}

package/dist/session.d.ts

@@ -0,0 +1,8 @@
+import { RetainfulSessionConfig, RetryConfig } from "./types/index";
+export declare class RetainfulSession {
+    private readonly client;
+    private readonly retryConfig?;
+    constructor(config: RetainfulSessionConfig, retryConfig?: RetryConfig);
+    post<TBody, TResponse>(path: string, body: TBody): Promise<TResponse>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EAGtB,WAAW,EACZ,MAAM,eAAe,CAAC;AAKvB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;gBAE/B,MAAM,EAAE,sBAAsB,EAAE,WAAW,CAAC,EAAE,WAAW;IAkB/D,IAAI,CAAC,KAAK,EAAE,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,SAAS,CAAC;CAqBtB"}

package/dist/session.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetainfulSession = void 0;
+const axios_1 = __importDefault(require("axios"));
+const index_1 = require("./types/index");
+const retry_1 = require("./utils/retry");
+const BASE_URL = "https://api.retainful.net";
+class RetainfulSession {
+    constructor(config, retryConfig) {
+        if (!config.apiKey) {
+            throw new index_1.RetainfulConfigError("Retainful API key is required. Get it from Settings → API Keys.");
+        }
+        this.retryConfig = retryConfig;
+        this.client = axios_1.default.create({
+            baseURL: BASE_URL,
+            headers: {
+                "Content-Type": "application/json",
+                "Retainful-Api-Key": config.apiKey,
+            },
+            timeout: 30000,
+        });
+    }
+    async post(path, body) {
+        return (0, retry_1.withRetry)(async () => {
+            try {
+                const response = await this.client.post(path, body);
+                return response.data;
+            }
+            catch (error) {
+                const axiosError = error;
+                if (axiosError.response) {
+                    throw new index_1.RetainfulApiError(axiosError.response.status, axiosError.response.statusText, axiosError.response.data);
+                }
+                throw error;
+            }
+        }, this.retryConfig);
+    }
+}
+exports.RetainfulSession = RetainfulSession;
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":";;;;;;AAAA,kDAAwE;AACxE,yCAKuB;AACvB,yCAA0C;AAE1C,MAAM,QAAQ,GAAG,2BAA2B,CAAC;AAE7C,MAAa,gBAAgB;IAI3B,YAAY,MAA8B,EAAE,WAAyB;QACnE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,4BAAoB,CAC5B,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAE/B,IAAI,CAAC,MAAM,GAAG,eAAK,CAAC,MAAM,CAAC;YACzB,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,mBAAmB,EAAE,MAAM,CAAC,MAAM;aACnC;YACD,OAAO,EAAE,KAAM;SAChB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CACR,IAAY,EACZ,IAAW;QAEX,OAAO,IAAA,iBAAS,EAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAA6B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAC/D,IAAI,EACJ,IAAI,CACL,CAAC;gBACF,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,UAAU,GAAG,KAAmB,CAAC;gBACvC,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;oBACxB,MAAM,IAAI,yBAAiB,CACzB,UAAU,CAAC,QAAQ,CAAC,MAAM,EAC1B,UAAU,CAAC,QAAQ,CAAC,UAAU,EAC9B,UAAU,CAAC,QAAQ,CAAC,IAAI,CACzB,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACvB,CAAC;CACF;AA9CD,4CA8CC"}

package/dist/types/index.d.ts

@@ -0,0 +1,98 @@
+export interface RetainfulSessionConfig {
+    /** Your Retainful API Key (from Settings → API Keys) */
+    apiKey: string;
+}
+export interface ShopifyAppConfig {
+    /** Human-readable name of your Shopify app, e.g. "Order Tracking Pro" */
+    appName: string;
+    /** URL-safe slug for your app, e.g. "order-tracking-pro" */
+    appSlug: string;
+}
+export interface RetryConfig {
+    /** HTTP status codes to retry on. Default: [429, 503, 504] */
+    retryCodes?: number[];
+    /** Number of retry attempts. Default: 3 */
+    numRetries?: number;
+    /** Maximum backoff interval in seconds. Default: 60 */
+    maxInterval?: number;
+}
+export interface ShopDetails {
+    /** Shopify store name */
+    name?: string;
+    /** Store owner's name */
+    ownerName?: string;
+    /** Store owner's phone */
+    phone?: string | null;
+    /** Shopify plan name, e.g. "basic", "shopify", "advanced" */
+    plan?: string;
+    /** Store's primary country */
+    country?: string;
+    /** Store currency, e.g. "USD" */
+    currency?: string;
+    /** Store's timezone */
+    timezone?: string;
+    /** Any extra Shopify store fields you want to forward */
+    [key: string]: unknown;
+}
+export type RetainfulEventType = "app/installed" | "app/uninstalled";
+/** Email subscription status as understood by Retainful. */
+export type EmailOptInStatus = "SUBSCRIBED" | "UNSUBSCRIBED" | (string & {});
+export interface AppEventPayload {
+    /** Type of lifecycle event */
+    eventType: RetainfulEventType;
+    /** Store owner / admin email — used as the contact identifier in Retainful */
+    email: string;
+    /** Shopify shop domain, e.g. "my-store.myshopify.com" — unique identifier */
+    shopDomain: string;
+    /** Full shop details object from Shopify */
+    shopDetails: ShopDetails;
+    /** Contact first name. Defaults to the first token of shopDetails.ownerName. */
+    firstName?: string;
+    /** Contact last name. Defaults to the remaining tokens of shopDetails.ownerName. */
+    lastName?: string;
+    /** Email subscription status. Default: "SUBSCRIBED" */
+    emailOptIn?: EmailOptInStatus;
+    /** Human-readable description. Default: "App installed" / "App uninstalled". */
+    description?: string;
+    /**
+     * Idempotency key for this event.
+     * Default: `${shopDomain}-${installed|uninstalled}`.
+     */
+    uniqueIdentifier?: string;
+    /** Extra fields merged into the eventData object sent to Retainful. */
+    eventData?: Record<string, unknown>;
+}
+export interface RetainfulContact {
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    phone?: string | null;
+    email_opt_in?: EmailOptInStatus;
+}
+export interface RetainfulEventRequest {
+    /** Display name of the event, e.g. "Order Tracking Pro installed". */
+    eventName: string;
+    /** Human-readable description of what happened. */
+    description?: string;
+    /** The contact this event is associated with. */
+    contact: RetainfulContact;
+    /** Arbitrary structured data attached to the event. */
+    eventData: Record<string, unknown>;
+    /** Idempotency key — dedupes repeated deliveries of the same event. */
+    uniqueIdentifier: string;
+}
+export interface RetainfulEventResponse {
+    success: boolean;
+    message?: string;
+    [key: string]: unknown;
+}
+export declare class RetainfulApiError extends Error {
+    readonly statusCode: number;
+    readonly statusText: string;
+    readonly responseData?: unknown;
+    constructor(statusCode: number, statusText: string, responseData?: unknown);
+}
+export declare class RetainfulConfigError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,27 @@
+"use strict";
+// ─────────────────────────────────────────────
+// Auth & Session Types
+// ─────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetainfulConfigError = exports.RetainfulApiError = void 0;
+// ─────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────
+class RetainfulApiError extends Error {
+    constructor(statusCode, statusText, responseData) {
+        super(`Retainful API Error ${statusCode}: ${statusText}`);
+        this.name = "RetainfulApiError";
+        this.statusCode = statusCode;
+        this.statusText = statusText;
+        this.responseData = responseData;
+    }
+}
+exports.RetainfulApiError = RetainfulApiError;
+class RetainfulConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RetainfulConfigError";
+    }
+}
+exports.RetainfulConfigError = RetainfulConfigError;
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA,gDAAgD;AAChD,uBAAuB;AACvB,gDAAgD;;;AAgIhD,gDAAgD;AAChD,SAAS;AACT,gDAAgD;AAEhD,MAAa,iBAAkB,SAAQ,KAAK;IAK1C,YAAY,UAAkB,EAAE,UAAkB,EAAE,YAAsB;QACxE,KAAK,CAAC,uBAAuB,UAAU,KAAK,UAAU,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAZD,8CAYC;AAED,MAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AALD,oDAKC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,7 @@
+import { RetryConfig } from "../types";
+/**
+ * Wraps an async function with retry logic using exponential backoff.
+ * Retries only on configured HTTP status codes.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAyBvC;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/utils/retry.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const DEFAULT_RETRY_CONFIG = {
+    retryCodes: [429, 503, 504],
+    numRetries: 3,
+    maxInterval: 60,
+};
+/**
+ * Sleep for a given number of milliseconds.
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Calculate exponential backoff delay with jitter.
+ * Formula: min(maxInterval, (2^attempt) * 1000) + random jitter
+ */
+const getBackoffDelay = (attempt, maxInterval) => {
+    const exponential = Math.pow(2, attempt) * 1000;
+    const capped = Math.min(maxInterval * 1000, exponential);
+    const jitter = Math.random() * 1000;
+    return capped + jitter;
+};
+/**
+ * Wraps an async function with retry logic using exponential backoff.
+ * Retries only on configured HTTP status codes.
+ */
+async function withRetry(fn, config) {
+    const { retryCodes, numRetries, maxInterval } = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...config,
+    };
+    let lastError;
+    for (let attempt = 0; attempt <= numRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Only retry on specific HTTP status codes
+            const statusCode = extractStatusCode(error);
+            const shouldRetry = attempt < numRetries &&
+                statusCode !== null &&
+                retryCodes.includes(statusCode);
+            if (!shouldRetry) {
+                throw error;
+            }
+            const delay = getBackoffDelay(attempt, maxInterval);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+function extractStatusCode(error) {
+    if (error &&
+        typeof error === "object" &&
+        "response" in error &&
+        error.response &&
+        typeof error.response === "object" &&
+        "status" in error.response &&
+        typeof error.response.status === "number") {
+        return error.response.status;
+    }
+    return null;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":";;AA6BA,8BAkCC;AA7DD,MAAM,oBAAoB,GAA0B;IAClD,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAC3B,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,EAAE;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,eAAe,GAAG,CAAC,OAAe,EAAE,WAAmB,EAAU,EAAE;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IACpC,OAAO,MAAM,GAAG,MAAM,CAAC;AACzB,CAAC,CAAC;AAEF;;;GAGG;AACI,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,MAAoB;IAEpB,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG;QAC9C,GAAG,oBAAoB;QACvB,GAAG,MAAM;KACV,CAAC;IAEF,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,SAAS,GAAG,KAAK,CAAC;YAElB,2CAA2C;YAC3C,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM,WAAW,GACf,OAAO,GAAG,UAAU;gBACpB,UAAU,KAAK,IAAI;gBACnB,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAElC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACpD,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,IACE,KAAK;QACL,OAAO,KAAK,KAAK,QAAQ;QACzB,UAAU,IAAI,KAAK;QACnB,KAAK,CAAC,QAAQ;QACd,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,QAAQ,IAAI,KAAK,CAAC,QAAQ;QAC1B,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,QAAQ,EACzC,CAAC;QACD,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "retainful-shopify-sdk",
+  "version": "1.0.2",
+  "description": "Retainful SDK for Shopify apps — Shopify lifecycle event tracking",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "trigger": "npm run build && node scripts/trigger-event.js"
+  },
+  "keywords": [
+    "retainful",
+    "shopify",
+    "yuko-apps",
+    "marketing-automation"
+  ],
+  "author": "Shopify Apps",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuko-app/Retainful-Shopify-apps-sdk.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}