@doswiftly/cli 0.1.24 → 0.2.1

package/templates/storefront-nextjs/.github/workflows/build-template.yml

@@ -1,119 +0,0 @@
-name: Build & Publish Template
-
-on:
-  push:
-    branches: [main, master]
-    tags: ['v*']
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to publish (e.g., 1.0.0)'
-        required: false
-
-env:
-  # Repository name (e.g., "default1", "minimal", "shadcn")
-  # Worker will be named: storefront-template-{TEMPLATE_NAME}
-  TEMPLATE_NAME: ${{ github.event.repository.name }}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Normalize template name
-        id: template
-        run: |
-          # Strip "storefront-" prefix if present
-          RAW_NAME="${{ env.TEMPLATE_NAME }}"
-          NORMALIZED="${RAW_NAME#storefront-}"
-          echo "name=${NORMALIZED}" >> $GITHUB_OUTPUT
-          echo "Template name: ${NORMALIZED}"
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Build for Cloudflare (OpenNext)
-        run: npx @opennextjs/cloudflare build
-
-      - name: List build output
-        run: |
-          echo "=== Build output ==="
-          ls -la .open-next/ || echo "No .open-next directory"
-          if [ -f ".open-next/worker.js" ]; then
-            echo "Worker size: $(wc -c < .open-next/worker.js) bytes"
-          fi
-
-      - name: Create deployment wrangler.toml
-        run: |
-          cat > .open-next/wrangler.toml << EOF
-          name = "storefront-template-${{ steps.template.outputs.name }}"
-          main = "worker.js"
-          compatibility_date = "2024-09-23"
-          compatibility_flags = ["nodejs_compat"]
-          assets = { directory = "assets", binding = "ASSETS" }
-
-          [observability]
-          enabled = true
-          head_sampling_rate = 1
-
-          [observability.logs]
-          enabled = true
-          head_sampling_rate = 1
-          persist = true
-          invocation_logs = true
-          EOF
-
-      - name: Determine version
-        id: version
-        run: |
-          if [ -n "${{ github.event.inputs.version }}" ]; then
-            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
-          elif [[ "${{ github.ref }}" == refs/tags/v* ]]; then
-            echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
-          else
-            echo "version=$(jq -r .version package.json)-$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Deploy to Cloudflare Workers
-        working-directory: .open-next
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-        run: |
-          if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
-            echo "⏭️ Skipping CF deploy (CLOUDFLARE_API_TOKEN not set)"
-            exit 0
-          fi
-          npx wrangler@latest deploy
-
-      - name: Upload worker bundle artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: worker-bundle
-          path: .open-next/
-          retention-days: 7
-          if-no-files-found: error
-          include-hidden-files: true
-
-      - name: Publish to DoSwiftly (on tag or manual)
-        if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
-        env:
-          DOSWIFTLY_TOKEN: ${{ secrets.DOSWIFTLY_DEPLOY_TOKEN }}
-          DOSWIFTLY_API_URL: ${{ secrets.DOSWIFTLY_API_URL }}
-        run: |
-          # Upload bundle to DoSwiftly R2 via API
-          curl -X POST "${DOSWIFTLY_API_URL}/cli/templates/${{ steps.template.outputs.name }}/publish" \
-            -H "Authorization: Bearer ${DOSWIFTLY_TOKEN}" \
-            -F "bundle=@.open-next/worker.js" \
-            -F "version=${{ steps.version.outputs.version }}"

package/templates/storefront-nextjs/README.md

@@ -1,524 +0,0 @@
-# DoSwiftly Storefront Template (DEPRECATED)
-
-> **DEPRECATED**: This template is no longer maintained. Use `storefront-nextjs-shadcn` instead, which follows the Hydrogen-style codegen-first architecture with local hook generation.
->
-> This template imports pre-built hooks from `@doswiftly/storefront-sdk/graphql/client|server` which are no longer exported as of SDK v3.0.0.
-
-A modern, production-ready e-commerce storefront built with Next.js 15 and the DoSwiftly Commerce SDK.
-
-## Features
-
-- ⚡ **Next.js 15** - App Router, Server Components, React 19
-- 🛒 **Commerce SDK** - Type-safe GraphQL API integration
-- 💱 **Multi-currency** - Automatic currency switching with SSR support
-- 🎨 **TailwindCSS** - Beautiful, responsive UI
-- 🔒 **Type-safe** - Full TypeScript support
-- 🚀 **Hybrid Architecture** - RSC for SEO, Client for interactivity
-
-## Quick Start
-
-```bash
-# Install dependencies
-pnpm install
-
-# Start development server
-pnpm dev
-```
-
----
-
-## Architecture: RSC vs Client Components
-
-This template uses a **hybrid architecture** that combines React Server Components (RSC) for performance and SEO with Client Components for interactivity.
-
-### When to Use RSC (Server)
-
-| Use Case            | Reason                  |
-| ------------------- | ----------------------- |
-| Product listings    | SEO, cacheability       |
-| Category pages      | SEO, static content     |
-| Collection pages    | SEO, static content     |
-| Search results      | SEO for search engines  |
-| Single product info | SEO, initial load speed |
-
-### When to Use Client Components
-
-| Use Case           | Reason                         |
-| ------------------ | ------------------------------ |
-| Shopping cart      | Real-time updates, mutations   |
-| Add to cart button | User interaction               |
-| Account/profile    | User-specific, mutations       |
-| Checkout           | Forms, payments, interactivity |
-| Currency selector  | Client-side state              |
-
-### Route Architecture
-
-```
-/app
-├── layout.tsx (RSC)
-│   └── providers.tsx (Client) ← QueryClient + StorefrontProvider
-│
-├── page.tsx (RSC) ← useProducts, useCategories
-├── products/
-│   ├── page.tsx (RSC) ← useProducts
-│   └── [slug]/page.tsx (RSC + Client island)
-│       └── <ProductActions/> (Client) ← Add to cart
-│
-├── categories/
-│   ├── page.tsx (RSC) ← useCategories
-│   └── [slug]/page.tsx (RSC) ← useCategory, useProducts
-│
-├── collections/
-│   ├── page.tsx (RSC) ← useCollections
-│   └── [slug]/page.tsx (RSC) ← useCollection, useProducts
-│
-├── search/page.tsx (RSC) ← useProducts
-│
-├── cart/page.tsx (Client) ← useCart, useCartLinesUpdate
-│
-├── account/
-│   ├── page.tsx (Client) ← useCustomer
-│   └── login/page.tsx (Client) ← useCustomerLogin
-│
-└── checkout/page.tsx (Client) ← Full interactivity
-```
-
----
-
-## Data Fetching
-
-> **🔑 IMPORTANT:** Both server and client return **normalized data** (flat arrays).  
-> GraphQL edges/nodes are automatically unwrapped. No `.edges.map((e) => e.node)` needed!
->
-> This provides the best developer experience and seamless migration between RSC and Client components.
-
-### Server Components (RSC)
-
-Import from `@doswiftly/storefront-sdk/graphql/server`:
-
-```typescript
-import {
-  useProducts,
-  useProduct,
-  useCategories,
-} from "@doswiftly/storefront-sdk/graphql/server";
-
-// All functions return normalized data (no edges/nodes)
-// Cached per-request via React cache()
-export default async function ProductsPage() {
-  const { products, pageInfo } = await useProducts({ first: 10 });
-  const { categories } = await useCategories();
-
-  // products is already a flat array - no .edges.map needed!
-  return <ProductGrid products={products} />;
-}
-```
-
-**Available server helpers:**
-
-- `useProducts()` - Product listings with pagination
-- `useProduct()` - Single product by handle
-- `useCategories()` - All categories
-- `useCategory()` - Single category by slug
-- `useCollections()` - All collections
-- `useCollection()` - Single collection by handle
-- `useCart()` - Cart by ID
-- `useShop()` - Shop configuration
-- `useCustomer()` - Authenticated customer data
-
-### Client Components
-
-Import from `@doswiftly/storefront-sdk/graphql/client`:
-
-```tsx
-"use client";
-
-import {
-  useProducts,
-  useCart,
-  useCartLinesAdd,
-} from "@doswiftly/storefront-sdk/graphql/client";
-
-export function ProductList() {
-  // React Query hook - returns normalized data (same as server!)
-  const { data, isLoading } = useProducts({ first: 10 });
-
-  if (isLoading) return <Skeleton />;
-
-  // data.products is already a flat array!
-  return <Grid products={data?.products} />;
-}
-
-export function AddToCartButton({ variantId }: { variantId: string }) {
-  const { mutate: addToCart, isPending } = useCartLinesAdd();
-
-  return (
-    <button
-      onClick={() =>
-        addToCart({
-          cartId,
-          lines: [{ merchandiseId: variantId, quantity: 1 }],
-        })
-      }
-      disabled={isPending}
-    >
-      {isPending ? "Adding..." : "Add to Cart"}
-    </button>
-  );
-}
-```
-
-**Available client hooks:**
-
-Queries:
-
-- `useProducts()` - Product listings
-- `useProduct()` - Single product
-- `useCategories()` - Categories
-- `useCategory()` - Single category
-- `useCollections()` - Collections
-- `useCollection()` - Single collection
-- `useCart()` - Cart data
-- `useCustomer()` - Customer data
-
-Mutations:
-
-- `useCartCreate()` - Create new cart
-- `useCartLinesAdd()` - Add items to cart
-- `useCartLinesUpdate()` - Update cart items
-- `useCartLinesRemove()` - Remove from cart
-- `useCustomerLogin()` - Login
-- `useCustomerCreate()` - Register
-- `useCustomerLogout()` - Logout
-
----
-
-## Naming Convention
-
-Both server and client use **identical function names AND return structures**:
-
-```typescript
-// Server (RSC) - async function, returns normalized data
-import { useProducts } from "@doswiftly/storefront-sdk/graphql/server";
-const { products, pageInfo } = await useProducts({ first: 10 });
-// products is a flat array ✅
-
-// Client - React Query hook, returns normalized data (same!)
-import { useProducts } from "@doswiftly/storefront-sdk/graphql/client";
-const { data } = useProducts({ first: 10 });
-const products = data?.products; // Also a flat array ✅
-```
-
-### Return Types Comparison
-
-| Aspect      | Server (`/server`)                    | Client (`/client`)                           |
-| ----------- | ------------------------------------- | -------------------------------------------- |
-| Return type | `Promise<NormalizedProductsResponse>` | `UseQueryResult<NormalizedProductsResponse>` |
-| Data access | `const { products, pageInfo }`        | `const { data }` → `data.products`           |
-| Data format | **Flat array** (normalized, no edges) | **Flat array** (normalized, no edges)        |
-| Loading     | N/A (await)                           | `isLoading`, `isFetching`                    |
-| Error       | try/catch                             | `error`, `isError`                           |
-| Refetch     | Call again                            | `refetch()`                                  |
-| Cache       | `React.cache()` per-request           | React Query client cache                     |
-
----
-
-## Authentication & Session Persistence
-
-### How It Works
-
-1. **Login** → `useCustomerLogin()` mutation returns token
-2. **Token stored** in cookie: `doswiftly_customer_token`
-3. **Page refresh**:
-   - RSC reads cookie → injects `X-Customer-Token` header
-   - Client hydrates with same state from server props
-4. **No flash of unauthenticated content**
-
-### Implementation
-
-```tsx
-// RSC - automatically authenticated via cookies
-import { useCustomer } from "@doswiftly/storefront-sdk/graphql/server";
-
-export default async function AccountPage() {
-  const { customer } = await useCustomer();
-
-  if (!customer) {
-    redirect("/login");
-  }
-
-  return <Profile customer={customer} />;
-}
-
-// Client - same pattern with loading state
-("use client");
-import { useCustomer, useAuth } from "@doswiftly/storefront-sdk/graphql/client";
-
-export function ProfileClient() {
-  const { data, isLoading } = useCustomer();
-  const { logout } = useAuth();
-
-  if (isLoading) return <Skeleton />;
-  if (!data?.customer) return <LoginPrompt />;
-
-  return <Profile customer={data.customer} onLogout={logout} />;
-}
-```
-
----
-
-## Currency Handling
-
-### Automatic Currency Injection
-
-Currency is read from `doswiftly_preferred_currency` cookie and automatically applied to all GraphQL requests.
-
-### Changing Currency
-
-```tsx
-"use client";
-import { useCurrency } from "@doswiftly/storefront-sdk/graphql/react";
-import { useRouter } from "next/navigation";
-
-export function CurrencySelector() {
-  const { currency, setCurrency, availableCurrencies } = useCurrency();
-  const router = useRouter();
-
-  const handleChange = (newCurrency: string) => {
-    setCurrency(newCurrency); // Updates cookie + context
-    router.refresh(); // Refreshes RSC pages with new currency
-  };
-
-  return (
-    <select value={currency} onChange={(e) => handleChange(e.target.value)}>
-      {availableCurrencies.map((c) => (
-        <option key={c} value={c}>
-          {c}
-        </option>
-      ))}
-    </select>
-  );
-}
-```
-
----
-
-## Filtering & Sorting
-
-### Filter Products
-
-```typescript
-const { products } = await useProducts({
-  first: 20,
-  filters: {
-    minPrice: 50,
-    maxPrice: 200,
-    vendor: "Nike",
-    available: true,
-  },
-  sortKey: "PRICE",
-  reverse: false, // ascending
-});
-```
-
-### Available Filters
-
-| Filter        | Type    | Description        |
-| ------------- | ------- | ------------------ |
-| `minPrice`    | number  | Minimum price      |
-| `maxPrice`    | number  | Maximum price      |
-| `vendor`      | string  | Brand/vendor name  |
-| `available`   | boolean | Stock availability |
-| `productType` | string  | Product type       |
-| `tag`         | string  | Product tag        |
-
-### Sort Keys
-
-- `TITLE` - Alphabetically
-- `PRICE` - By price
-- `CREATED_AT` - By date
-- `BEST_SELLING` - By popularity
-
----
-
-## Pagination
-
-Cursor-based pagination for all list endpoints:
-
-```typescript
-const { products, pageInfo } = await useProducts({ first: 10 });
-
-if (pageInfo?.hasNextPage) {
-  const nextPage = await useProducts({
-    first: 10,
-    after: pageInfo.endCursor,
-  });
-}
-```
-
----
-
-## Island of Interactivity Pattern
-
-Combine RSC and Client Components for optimal performance:
-
-```tsx
-// app/products/[slug]/page.tsx (RSC)
-import { useProduct } from "@doswiftly/storefront-sdk/graphql/server";
-import { AddToCartButton } from "@/components/commerce/add-to-cart";
-
-export default async function ProductPage({ params }) {
-  const { product } = await useProduct({ handle: params.slug });
-
-  return (
-    <div>
-      {/* RSC - Static, SEO-friendly */}
-      <h1>{product.title}</h1>
-      <p>{product.description}</p>
-      <img src={product.featuredImage?.url} alt={product.title} />
-
-      {/* Client Island - Interactive */}
-      <AddToCartButton productId={product.id} variants={product.variants} />
-    </div>
-  );
-}
-```
-
-```tsx
-// components/commerce/add-to-cart.tsx (Client)
-"use client";
-
-import { useCartManager } from "@doswiftly/storefront-sdk/graphql/react";
-
-export function AddToCartButton({ productId, variants }) {
-  const { addItem, loading } = useCartManager();
-  const [quantity, setQuantity] = useState(1);
-  const [selectedVariant, setSelectedVariant] = useState(variants[0]?.id);
-
-  return (
-    <div>
-      <QuantitySelector value={quantity} onChange={setQuantity} />
-      <VariantSelector
-        variants={variants}
-        value={selectedVariant}
-        onChange={setSelectedVariant}
-      />
-      <button
-        onClick={() => addItem(selectedVariant, quantity)}
-        disabled={loading}
-      >
-        {loading ? "Adding..." : "Add to Cart"}
-      </button>
-    </div>
-  );
-}
-```
-
----
-
-## Environment Variables
-
-```env
-# Required
-NEXT_PUBLIC_API_URL=http://localhost:8000
-NEXT_PUBLIC_SHOP_SLUG=your-shop-slug
-
-# Optional
-NEXT_PUBLIC_SITE_NAME=My Store
-```
-
----
-
-## Project Structure
-
-```
-app/
-  layout.tsx              # Root layout (RSC)
-  page.tsx                # Homepage (RSC)
-  products/
-    page.tsx              # Product listing (RSC)
-    [slug]/page.tsx       # Product detail (RSC + Client)
-  categories/
-    page.tsx              # Categories (RSC)
-    [slug]/page.tsx       # Category products (RSC)
-  collections/
-    page.tsx              # Collections (RSC)
-    [slug]/page.tsx       # Collection products (RSC)
-  search/page.tsx         # Search results (RSC)
-  cart/page.tsx           # Shopping cart (Client)
-  account/
-    page.tsx              # Account dashboard (Client)
-    login/page.tsx        # Login form (Client)
-
-components/
-  commerce/
-    add-to-cart.tsx       # Add to cart button (Client)
-    currency-selector.tsx # Currency switcher (Client)
-    product-actions.tsx   # Product page actions (Client)
-  providers.tsx           # QueryClient + StorefrontProvider (Client)
-```
-
----
-
-## Migration from Raw GraphQL
-
-If you're migrating from a previous version that returned raw GraphQL responses (edges/nodes), here's what changed:
-
-### ✅ Before (Raw GraphQL)
-
-```tsx
-// Client hooks returned raw edges/nodes
-const { data } = useProducts({ first: 10 });
-const products = data?.products.edges.map((e) => e.node);
-```
-
-### ✅ After (Normalized)
-
-```tsx
-// Client hooks now return flat arrays (same as server)
-const { data } = useProducts({ first: 10 });
-const products = data?.products; // Already flat!
-```
-
-### Migration Steps
-
-1. **Remove `.edges.map((e) => e.node)`** from all client components
-2. **Access data directly**: `data.products` instead of `data.products.edges`
-3. **PageInfo unchanged**: Still accessed via `data.pageInfo`
-
-### Why This Change?
-
-- **Consistency**: Server and client APIs are now identical
-- **Developer Experience**: Zero boilerplate, less code
-- **Fewer Errors**: No more "Cannot read properties of undefined (reading 'map')"
-- **Seamless Migration**: Move components between RSC/Client without changes
-
-### Need Raw GraphQL?
-
-For advanced use cases requiring raw GraphQL (custom fragments, \_\_typename, etc.), use `graphql-request` directly:
-
-```typescript
-import { GraphQLClient } from "graphql-request";
-import { gql } from "graphql-tag";
-
-const client = new GraphQLClient(apiUrl);
-const data = await client.request(gql`
-  query {
-    products(first: 10) {
-      edges {
-        node {
-          id
-          __typename
-        }
-        cursor
-      }
-    }
-  }
-`);
-```
-
----
-
-## License
-
-MIT