@doswiftly/storefront-operations 1.0.5

package/README.md

@@ -0,0 +1,195 @@
+# @doswiftly/storefront-operations
+
+Pre-built GraphQL operations for DoSwiftly e-commerce storefronts. Contains ready-to-use queries, mutations, and fragments for products, collections, cart, checkout, and customer management.
+
+## Installation
+
+```bash
+npm install @doswiftly/storefront-operations
+# or
+pnpm add @doswiftly/storefront-operations
+```
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+npm install @doswiftly/storefront-operations @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node
+```
+
+### 2. Create `codegen.ts`
+
+```typescript
+import { CodegenConfig } from "@graphql-codegen/cli";
+
+const config: CodegenConfig = {
+  schema: {
+    [process.env.NEXT_PUBLIC_STOREFRONT_API_URL!]: {
+      headers: {
+        "X-Shop-Slug": process.env.NEXT_PUBLIC_SHOP_SLUG!,
+      },
+    },
+  },
+  documents: [
+    "node_modules/@doswiftly/storefront-operations/**/*.graphql",
+    "src/**/*.{ts,tsx}", // Your custom operations (optional)
+  ],
+  generates: {
+    "src/generated/graphql.ts": {
+      plugins: ["typescript", "typescript-operations", "typed-document-node"],
+    },
+  },
+};
+
+export default config;
+```
+
+### 3. Add script to `package.json`
+
+```json
+{
+  "scripts": {
+    "codegen": "graphql-codegen --config codegen.ts"
+  }
+}
+```
+
+### 4. Run codegen
+
+```bash
+npm run codegen
+```
+
+### 5. Use in your components
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { graphqlClient } from '@/lib/graphql-client';
+import { ProductsDocument } from '@/generated/graphql';
+
+export function ProductList() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['products'],
+    queryFn: () => graphqlClient.request(ProductsDocument, { first: 12 }),
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {data?.products.edges.map(({ node }) => (
+        <ProductCard key={node.id} product={node} />
+      ))}
+    </div>
+  );
+}
+```
+
+## Available Operations
+
+### Queries
+
+| Operation           | Description                              |
+| ------------------- | ---------------------------------------- |
+| `Shop`              | Shop configuration, currencies, settings |
+| `Product`           | Single product by ID or handle           |
+| `Products`          | Product list with pagination and filters |
+| `ProductSearch`     | Full-text product search                 |
+| `Collection`        | Collection with its products             |
+| `Collections`       | All collections                          |
+| `Category`          | Category with hierarchy                  |
+| `Categories`        | Category tree                            |
+| `Cart`              | Cart contents by ID                      |
+| `Customer`          | Logged-in customer data                  |
+| `CustomerOrders`    | Customer order history                   |
+| `CustomerAddresses` | Customer saved addresses                 |
+
+### Mutations
+
+**Cart**
+
+- `CartCreate` - Create a new cart
+- `CartLinesAdd` - Add items to cart
+- `CartLinesUpdate` - Update item quantities
+- `CartLinesRemove` - Remove items from cart
+- `CartDiscountCodesUpdate` - Apply/remove discount codes
+- `CartBuyerIdentityUpdate` - Set customer info on cart
+- `CartNoteUpdate` - Add note to cart
+
+**Authentication**
+
+- `CustomerCreate` - Register new customer
+- `CustomerLogin` - Login and get token
+- `CustomerLogout` - Logout
+- `CustomerTokenRenew` - Refresh auth token
+
+**Customer Profile**
+
+- `CustomerUpdate` - Update profile info
+- `CustomerAddressCreate` - Add new address
+- `CustomerAddressUpdate` - Update address
+- `CustomerAddressDelete` - Delete address
+- `CustomerDefaultAddressUpdate` - Set default address
+
+**Password**
+
+- `CustomerPasswordRecover` - Request password reset email
+- `CustomerPasswordReset` - Reset password with token
+
+## Environment Variables
+
+```env
+NEXT_PUBLIC_STOREFRONT_API_URL=https://api.doswiftly.pl/storefront/graphql
+NEXT_PUBLIC_SHOP_SLUG=your-shop-slug
+```
+
+## TypeScript Support
+
+All operations are fully typed. After running codegen, you get:
+
+- Document nodes for each operation
+- Input types for variables
+- Response types for results
+
+```typescript
+import {
+  ProductDocument,
+  ProductQuery,
+  ProductQueryVariables,
+} from "@/generated/graphql";
+
+// Full type safety
+const variables: ProductQueryVariables = {
+  handle: "awesome-product",
+};
+```
+
+## Custom Operations
+
+You can add your own GraphQL operations alongside the package operations:
+
+```graphql
+# src/graphql/custom-queries.graphql
+query FeaturedProducts {
+  products(first: 4, filters: { tag: "featured" }) {
+    edges {
+      node {
+        ...ProductCard
+      }
+    }
+  }
+}
+```
+
+Re-run `npm run codegen` to generate types for your custom operations.
+
+## Links
+
+- [DoSwiftly Website](https://doswiftly.pl)
+- [DoSwiftly Documentation](https://doswiftly.pl/docs)
+- [GraphQL API Reference](https://doswiftly.pl/docs/api/graphql)
+
+## License
+
+MIT