@porulle/import-shopify 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @porulle/import-shopify
+
+Import a Shopify store's catalog into Porulle. Maps Shopify's product / variant / option / image model onto `sellable_entities`, `variants`, `option_types`, `option_values`, `entity_media`.
+
+## Usage
+
+Export your Shopify catalog (JSON via the Admin API or `shopify CLI products list --json`):
+
+```bash
+shopify products list --json > shopify-catalog.json
+porulle import ./shopify-catalog.json --format shopify
+```
+
+Or programmatically:
+
+```ts
+import { importShopifyProducts } from "@porulle/import-shopify";
+import { commerce } from "./server";
+
+const products = JSON.parse(await fs.readFile("./shopify-catalog.json", "utf-8"));
+const result = await importShopifyProducts(commerce.api, products);
+if (!result.ok) {
+  console.error("import failed:", result.error);
+  process.exit(1);
+}
+```
+
+## What it maps
+
+| Shopify | Porulle |
+|---|---|
+| `Product` | `sellable_entities` (type: `product`) |
+| `Variant` | `variants` |
+| `Option` (Size, Color, …) | `option_types` + `option_values` |
+| `Image` | `media_assets` + `entity_media` (role: gallery / primary) |
+| `tags` | `metadata.tags` |
+| `vendor` | `metadata.vendor` (or wired to a brand if you've enabled brands) |
+
+## What it doesn't map
+
+- Customers — Shopify customer export needs PII review; bring your own migration script
+- Orders — Porulle doesn't import historical orders (different schema, different fulfillment state machine)
+- Discounts — Shopify's discount engine is shaped differently; rebuild as Porulle promotions
+- Apps / themes / scripts — out of scope
+
+## See also
+
+- `@porulle/import-flat` — neutral JSON format
+- `@porulle/import-woocommerce` — for WooCommerce origins
+- [Shopify Admin API — Product](https://shopify.dev/docs/api/admin-rest/latest/resources/product)

package/dist/src/index.d.ts

@@ -0,0 +1,156 @@
+import { type Result } from "@porulle/core";
+export interface ShopifyImage {
+    id: number;
+    src: string;
+    alt?: string | null;
+}
+export interface ShopifyProductOption {
+    id?: number;
+    name: string;
+    position?: number;
+    values: string[];
+}
+export interface ShopifyVariant {
+    id: number;
+    title?: string;
+    sku?: string;
+    barcode?: string;
+    price?: string;
+    compare_at_price?: string | null;
+    option1?: string | null;
+    option2?: string | null;
+    option3?: string | null;
+}
+export interface ShopifyProduct {
+    id: number;
+    title: string;
+    handle?: string;
+    body_html?: string;
+    product_type?: string;
+    vendor?: string;
+    tags?: string;
+    options?: ShopifyProductOption[];
+    variants?: ShopifyVariant[];
+    images?: ShopifyImage[];
+}
+export interface ShopifyAddress {
+    first_name?: string;
+    last_name?: string;
+    address1?: string;
+    address2?: string;
+    city?: string;
+    province?: string;
+    zip?: string;
+    country_code?: string;
+    phone?: string;
+    default?: boolean;
+}
+export interface ShopifyCustomer {
+    id: number;
+    email?: string;
+    phone?: string;
+    first_name?: string;
+    last_name?: string;
+    addresses?: ShopifyAddress[];
+}
+export interface ShopifyImportTarget {
+    createEntity(input: {
+        type: string;
+        slug: string;
+        attributes: {
+            title: string;
+            description?: string;
+        };
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    createOptionType?(input: {
+        entityId: string;
+        name: string;
+        displayName: string;
+        sortOrder?: number;
+    }): Promise<{
+        id: string;
+    }>;
+    createOptionValue?(input: {
+        optionTypeId: string;
+        value: string;
+        displayValue: string;
+        sortOrder?: number;
+    }): Promise<{
+        id: string;
+    }>;
+    createVariant?(input: {
+        entityId: string;
+        optionValueIds: string[];
+        sku?: string;
+        barcode?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    uploadMedia?(input: {
+        filename: string;
+        contentType: string;
+        data: ArrayBuffer;
+        alt?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+        url: string;
+    }>;
+    attachMedia?(input: {
+        entityId: string;
+        mediaAssetId: string;
+        role: "primary" | "gallery";
+    }): Promise<void>;
+    upsertCustomer?(input: {
+        userId: string;
+        email?: string;
+        phone?: string;
+        firstName?: string;
+        lastName?: string;
+        addresses?: Array<{
+            type: "shipping" | "billing";
+            isDefault: boolean;
+            firstName: string;
+            lastName: string;
+            line1: string;
+            line2?: string;
+            city: string;
+            state?: string;
+            postalCode?: string;
+            country: string;
+            phone?: string;
+        }>;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+}
+export interface ShopifyImportOptions {
+    target: ShopifyImportTarget;
+    apiKey?: string;
+    storeUrl?: string;
+    apiVersion?: string;
+    products?: ShopifyProduct[];
+    customers?: ShopifyCustomer[];
+    fetchImpl?: typeof fetch;
+    mediaFetcher?: (url: string) => Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+        filename?: string;
+    }>;
+    entityType?: string;
+}
+export interface ShopifyImportSummary {
+    entitiesImported: number;
+    variantsImported: number;
+    mediaImported: number;
+    customersImported: number;
+    errors: Array<{
+        scope: "entity" | "variant" | "media" | "customer";
+        message: string;
+    }>;
+}
+export declare function importShopifyCatalog(options: ShopifyImportOptions): Promise<Result<ShopifyImportSummary>>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/src/index.js

@@ -0,0 +1,273 @@
+import { Err, Ok } from "@porulle/core";
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || `product-${crypto.randomUUID().slice(0, 8)}`;
+}
+function parseMoney(value) {
+    if (!value)
+        return 0;
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed))
+        return 0;
+    return Math.round(parsed * 100);
+}
+async function fetchJson(fetchImpl, url, apiKey) {
+    try {
+        const response = await fetchImpl(url, {
+            headers: {
+                "x-shopify-access-token": apiKey,
+                accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            return Err({
+                code: "SHOPIFY_API_FAILED",
+                message: `Shopify API request failed (${response.status}) for ${url}.`,
+            });
+        }
+        return Ok((await response.json()));
+    }
+    catch (error) {
+        return Err({
+            code: "SHOPIFY_API_FAILED",
+            message: error instanceof Error ? error.message : "Shopify API request failed.",
+        });
+    }
+}
+function filenameFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const last = parsed.pathname.split("/").filter(Boolean).pop();
+        return last && last.length > 0 ? last : `media-${crypto.randomUUID().slice(0, 8)}.bin`;
+    }
+    catch {
+        return `media-${crypto.randomUUID().slice(0, 8)}.bin`;
+    }
+}
+async function defaultMediaFetcher(fetchImpl, url) {
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download media (${response.status}) from ${url}`);
+    }
+    return {
+        data: await response.arrayBuffer(),
+        contentType: response.headers.get("content-type") ?? "application/octet-stream",
+        filename: filenameFromUrl(url),
+    };
+}
+async function loadProducts(options) {
+    if (options.products)
+        return Ok(options.products);
+    if (!options.storeUrl || !options.apiKey) {
+        return Err({
+            code: "SHOPIFY_INPUT_REQUIRED",
+            message: "Provide products or both storeUrl and apiKey for Shopify import.",
+        });
+    }
+    const base = options.storeUrl.replace(/\/$/, "");
+    const version = options.apiVersion ?? "2024-10";
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchJson(fetchImpl, `${base}/admin/api/${version}/products.json?limit=250`, options.apiKey);
+    if (!response.ok)
+        return response;
+    return Ok(response.value.products ?? []);
+}
+async function loadCustomers(options) {
+    if (options.customers)
+        return Ok(options.customers);
+    if (!options.storeUrl || !options.apiKey) {
+        return Ok([]);
+    }
+    const base = options.storeUrl.replace(/\/$/, "");
+    const version = options.apiVersion ?? "2024-10";
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchJson(fetchImpl, `${base}/admin/api/${version}/customers.json?limit=250`, options.apiKey);
+    if (!response.ok)
+        return response;
+    return Ok(response.value.customers ?? []);
+}
+function toAddress(address) {
+    return {
+        type: "shipping",
+        isDefault: address.default ?? false,
+        firstName: address.first_name ?? "",
+        lastName: address.last_name ?? "",
+        line1: address.address1 ?? "",
+        ...(address.address2 ? { line2: address.address2 } : {}),
+        city: address.city ?? "",
+        ...(address.province ? { state: address.province } : {}),
+        ...(address.zip ? { postalCode: address.zip } : {}),
+        country: address.country_code ?? "US",
+        ...(address.phone ? { phone: address.phone } : {}),
+    };
+}
+export async function importShopifyCatalog(options) {
+    const productsResult = await loadProducts(options);
+    if (!productsResult.ok)
+        return productsResult;
+    const customersResult = await loadCustomers(options);
+    if (!customersResult.ok)
+        return customersResult;
+    const summary = {
+        entitiesImported: 0,
+        variantsImported: 0,
+        mediaImported: 0,
+        customersImported: 0,
+        errors: [],
+    };
+    const mediaFetcher = options.mediaFetcher
+        ? options.mediaFetcher
+        : async (url) => defaultMediaFetcher(options.fetchImpl ?? fetch, url);
+    for (const product of productsResult.value) {
+        try {
+            const createdEntity = await options.target.createEntity({
+                type: options.entityType ?? "product",
+                slug: product.handle ? slugify(product.handle) : slugify(product.title),
+                attributes: {
+                    title: product.title,
+                    ...(product.body_html ? { description: product.body_html } : {}),
+                },
+                metadata: {
+                    source: "shopify",
+                    shopifyProductId: product.id,
+                    productType: product.product_type,
+                    vendor: product.vendor,
+                    tags: product.tags,
+                },
+            });
+            summary.entitiesImported += 1;
+            const optionTypeIdByName = new Map();
+            const optionValueIdByKey = new Map();
+            if (options.target.createOptionType && options.target.createOptionValue) {
+                const optionList = product.options ?? [];
+                for (let optionIndex = 0; optionIndex < optionList.length; optionIndex += 1) {
+                    const option = optionList[optionIndex];
+                    const createdType = await options.target.createOptionType({
+                        entityId: createdEntity.id,
+                        name: option.name,
+                        displayName: option.name,
+                        sortOrder: option.position ?? optionIndex,
+                    });
+                    optionTypeIdByName.set(option.name, createdType.id);
+                    for (let valueIndex = 0; valueIndex < option.values.length; valueIndex += 1) {
+                        const value = option.values[valueIndex];
+                        const createdValue = await options.target.createOptionValue({
+                            optionTypeId: createdType.id,
+                            value,
+                            displayValue: value,
+                            sortOrder: valueIndex,
+                        });
+                        optionValueIdByKey.set(`${option.name}::${value}`, createdValue.id);
+                    }
+                }
+            }
+            if (options.target.createVariant && (product.variants?.length ?? 0) > 0) {
+                for (const variant of product.variants ?? []) {
+                    try {
+                        const optionValues = [];
+                        const selectors = [variant.option1, variant.option2, variant.option3];
+                        const productOptions = product.options ?? [];
+                        for (let idx = 0; idx < selectors.length; idx += 1) {
+                            const selected = selectors[idx];
+                            if (!selected)
+                                continue;
+                            const optionName = productOptions[idx]?.name;
+                            if (!optionName)
+                                continue;
+                            const optionValueId = optionValueIdByKey.get(`${optionName}::${selected}`);
+                            if (optionValueId) {
+                                optionValues.push(optionValueId);
+                            }
+                        }
+                        await options.target.createVariant({
+                            entityId: createdEntity.id,
+                            optionValueIds: optionValues,
+                            ...(variant.sku ? { sku: variant.sku } : {}),
+                            ...(variant.barcode ? { barcode: variant.barcode } : {}),
+                            metadata: {
+                                source: "shopify",
+                                shopifyVariantId: variant.id,
+                                title: variant.title,
+                                price: parseMoney(variant.price),
+                                compareAtPrice: parseMoney(variant.compare_at_price),
+                            },
+                        });
+                        summary.variantsImported += 1;
+                    }
+                    catch (error) {
+                        summary.errors.push({
+                            scope: "variant",
+                            message: error instanceof Error ? error.message : "Variant import failed.",
+                        });
+                    }
+                }
+            }
+            if (options.target.uploadMedia && options.target.attachMedia) {
+                const images = product.images ?? [];
+                for (let imageIndex = 0; imageIndex < images.length; imageIndex += 1) {
+                    const image = images[imageIndex];
+                    try {
+                        const downloaded = await mediaFetcher(image.src);
+                        const uploaded = await options.target.uploadMedia({
+                            filename: downloaded.filename ?? filenameFromUrl(image.src),
+                            contentType: downloaded.contentType,
+                            data: downloaded.data,
+                            ...(image.alt ? { alt: image.alt } : {}),
+                            metadata: {
+                                source: "shopify",
+                                shopifyImageId: image.id,
+                            },
+                        });
+                        await options.target.attachMedia({
+                            entityId: createdEntity.id,
+                            mediaAssetId: uploaded.id,
+                            role: imageIndex === 0 ? "primary" : "gallery",
+                        });
+                        summary.mediaImported += 1;
+                    }
+                    catch (error) {
+                        summary.errors.push({
+                            scope: "media",
+                            message: error instanceof Error ? error.message : "Media import failed.",
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            summary.errors.push({
+                scope: "entity",
+                message: error instanceof Error ? error.message : "Entity import failed.",
+            });
+        }
+    }
+    if (options.target.upsertCustomer) {
+        for (const customer of customersResult.value) {
+            try {
+                await options.target.upsertCustomer({
+                    userId: `shopify:${customer.id}`,
+                    ...(customer.email ? { email: customer.email } : {}),
+                    ...(customer.phone ? { phone: customer.phone } : {}),
+                    ...(customer.first_name ? { firstName: customer.first_name } : {}),
+                    ...(customer.last_name ? { lastName: customer.last_name } : {}),
+                    addresses: (customer.addresses ?? []).map((address) => toAddress(address)),
+                    metadata: {
+                        source: "shopify",
+                        shopifyCustomerId: customer.id,
+                    },
+                });
+                summary.customersImported += 1;
+            }
+            catch (error) {
+                summary.errors.push({
+                    scope: "customer",
+                    message: error instanceof Error ? error.message : "Customer import failed.",
+                });
+            }
+        }
+    }
+    return Ok(summary);
+}