medusa-gift-wrap-logic 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# Medusa Gift Wrap Logic
+
+A reusable gift-wrap hook and service for Medusa storefronts. This package provides the logic necessary to manage per-line-item gift metadata without any UI dependencies.
+
+## Features
+
+- **Per-Line-Item Gift Metadata**: Easily apply gift metadata (`is_gift`, `gift_from`, `gift_to`, `gift_message`) directly to line items in the cart.
+- **Headless & UI Agnostic**: Contains only the business logic and hooks. You can build your own UI components using these hooks.
+- **Medusa Compatible**: Works seamlessly with `@medusajs/js-sdk` and `@medusajs/types`.
+- **TypeScript Ready**: Written in TypeScript and provides complete type definitions.
+
+## Installation
+
+```bash
+npm install medusa-gift-wrap-logic
+```
+
+## Setup
+
+First, make sure you have the required peer dependencies installed in your project:
+
+```bash
+npm install react react-dom
+```
+
+## Basic Usage
+
+The package exports a custom React hook that you can use in your React storefront or Next.js app to handle gift-wrapping logic for any product inside the cart.
+
+```tsx
+import { useGiftWrap } from 'medusa-gift-wrap-logic';
+
+export default function GiftWrapComponent({ lineItemId }) {
+  const { isGift, setGiftInfo, updateLineItem, isUpdating } = useGiftWrap(lineItemId);
+  
+  // Implementation of your UI based on the state returned from the hook
+}
+```
+
+## Development
+
+- `npm run dev` - Starts Vite development server
+- `npm run build` - Builds the package using TypeScript and Vite
+- `npm run preview` - Previews the build
+
+## Requirements
+- `react` 18 or 19
+- `@medusajs/js-sdk` v2+

package/dist/gift-wrap-logic/src/hooks/useGiftWrap.d.ts

@@ -0,0 +1,55 @@
+import { HttpTypes } from '@medusajs/types';
+import { default as Medusa } from '@medusajs/js-sdk';
+import { GiftMetadata } from '../../../medusa-services/gift-wrap';
+
+export interface GiftFormState {
+    giftFrom: string;
+    giftTo: string;
+    giftMessage: string;
+}
+export interface UseGiftWrapOptions {
+    /** The cart line item to manage gift state for */
+    item: HttpTypes.StoreCartLineItem;
+    /** Initialised Medusa JS SDK instance */
+    sdk: Medusa;
+    /** Cart ID that owns the line item */
+    cartId: string;
+    /** Called after a successful save or remove (e.g. to trigger a page refresh) */
+    onSuccess?: () => void;
+    /** Called when an API error occurs */
+    onError?: (error: Error) => void;
+}
+export interface UseGiftWrapReturn {
+    /** Whether the item is currently marked as a gift */
+    isGift: boolean;
+    /** Whether any personalisation details (from/to/message) have been set */
+    hasDetails: boolean;
+    /** The raw gift metadata from the line item */
+    giftMetadata: GiftMetadata;
+    /** Whether the gift details modal should be open */
+    showModal: boolean;
+    /** Current values of the gift form fields */
+    form: GiftFormState;
+    /** True while the save mutation is in flight */
+    loading: boolean;
+    /** True while the remove mutation is in flight */
+    removing: boolean;
+    /** Last API error message, or null */
+    error: string | null;
+    /** Open the gift details modal (pre-populates form from existing metadata) */
+    openModal: () => void;
+    /** Close the gift details modal without saving */
+    closeModal: () => void;
+    /**
+     * Handler for the gift checkbox — opens the modal when checking,
+     * triggers removal when unchecking (delegates to handleRemove).
+     */
+    handleCheck: () => void;
+    /** Save the current form values as gift metadata */
+    handleSubmit: () => Promise<void>;
+    /** Remove the gift flag and all personalisation fields */
+    handleRemove: () => Promise<void>;
+    /** Update a single form field by key */
+    setFormField: (field: keyof GiftFormState, value: string) => void;
+}
+export declare function useGiftWrap({ item, sdk, cartId, onSuccess, onError, }: UseGiftWrapOptions): UseGiftWrapReturn;

package/dist/gift-wrap-logic/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './hooks/useGiftWrap';
+export * from '../../medusa-services/gift-wrap';

package/dist/medusa-services/gift-wrap.d.ts

@@ -0,0 +1,29 @@
+export interface GiftMetadata {
+    is_gift?: boolean;
+    gift_from?: string;
+    gift_to?: string;
+    gift_message?: string;
+    [key: string]: unknown;
+}
+export interface UpdateGiftMetadataOptions {
+    sdk: any;
+    cartId: string;
+    lineId: string;
+    quantity: number;
+    metadata: GiftMetadata;
+}
+export interface RemoveGiftMetadataOptions {
+    sdk: any;
+    cartId: string;
+    lineId: string;
+    quantity: number;
+    existingMeta: GiftMetadata;
+}
+/**
+ * Updates the metadata for a specific line item in a cart to include gift information.
+ */
+export declare function updateGiftMetadata({ sdk, cartId, lineId, quantity, metadata, }: UpdateGiftMetadataOptions): Promise<any>;
+/**
+ * Removes gift-related metadata from a specific line item in a cart.
+ */
+export declare function removeGiftMetadata({ sdk, cartId, lineId, quantity, existingMeta, }: RemoveGiftMetadataOptions): Promise<any>;

package/dist/ui-library.js

@@ -0,0 +1,126 @@
+import { useState as d, useCallback as n } from "react";
+async function C({
+  sdk: a,
+  cartId: g,
+  lineId: o,
+  quantity: e,
+  metadata: i
+}) {
+  return await a.store.cart.updateLineItem(g, o, {
+    quantity: e,
+    metadata: i
+  });
+}
+async function R({
+  sdk: a,
+  cartId: g,
+  lineId: o,
+  quantity: e,
+  existingMeta: i
+}) {
+  const {
+    is_gift: t,
+    gift_from: _,
+    gift_to: y,
+    gift_message: M,
+    ...l
+  } = i;
+  return await a.store.cart.updateLineItem(g, o, {
+    quantity: e,
+    metadata: {
+      ...l,
+      is_gift: !1,
+      gift_from: "",
+      gift_to: "",
+      gift_message: ""
+    }
+  });
+}
+function I({
+  item: a,
+  sdk: g,
+  cartId: o,
+  onSuccess: e,
+  onError: i
+}) {
+  const t = a.metadata ?? {}, _ = t.is_gift === !0, y = !!t.gift_from || !!t.gift_to || !!t.gift_message, [M, l] = d(!1), [F, p] = d(!1), [q, w] = d(!1), [v, m] = d(null), [r, h] = d({
+    giftFrom: "",
+    giftTo: "",
+    giftMessage: ""
+  }), c = n(() => {
+    h({
+      giftFrom: t.gift_from ?? "",
+      giftTo: t.gift_to ?? "",
+      giftMessage: t.gift_message ?? ""
+    }), m(null), l(!0);
+  }, [t.gift_from, t.gift_to, t.gift_message]), G = n(() => {
+    l(!1);
+  }, []), T = n(() => {
+    _ || c();
+  }, [_, c]), B = n(
+    (f, s) => {
+      h((u) => ({ ...u, [f]: s }));
+    },
+    []
+  ), L = n(async () => {
+    m(null), p(!0);
+    try {
+      const f = r.giftFrom.trim(), s = r.giftTo.trim(), u = r.giftMessage.trim(), x = {
+        ...t,
+        is_gift: !0,
+        ...f && { gift_from: f },
+        ...s && { gift_to: s },
+        ...u && { gift_message: u }
+      };
+      await C({
+        sdk: g,
+        cartId: o,
+        lineId: a.id,
+        quantity: a.quantity,
+        metadata: x
+      }), l(!1), e == null || e();
+    } catch (f) {
+      const s = f instanceof Error ? f : new Error("Failed to save gift");
+      m(s.message), i == null || i(s);
+    } finally {
+      p(!1);
+    }
+  }, [r, t, g, o, a.id, a.quantity, e, i]), b = n(async () => {
+    w(!0), m(null);
+    try {
+      await R({
+        sdk: g,
+        cartId: o,
+        lineId: a.id,
+        quantity: a.quantity,
+        existingMeta: t
+      }), e == null || e();
+    } catch (f) {
+      const s = f instanceof Error ? f : new Error("Failed to remove gift");
+      m(s.message), i == null || i(s);
+    } finally {
+      w(!1);
+    }
+  }, [t, g, o, a.id, a.quantity, e, i]);
+  return {
+    isGift: _,
+    hasDetails: y,
+    giftMetadata: t,
+    showModal: M,
+    form: r,
+    loading: F,
+    removing: q,
+    error: v,
+    openModal: c,
+    closeModal: G,
+    handleCheck: T,
+    handleSubmit: L,
+    handleRemove: b,
+    setFormField: B
+  };
+}
+export {
+  R as removeGiftMetadata,
+  C as updateGiftMetadata,
+  I as useGiftWrap
+};

package/dist/ui-library.umd.cjs

@@ -0,0 +1 @@
+(function(o,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],e):(o=typeof globalThis<"u"?globalThis:o||self,e(o.MedusaGiftWrapLogic={},o.React))})(this,function(o,e){"use strict";async function c({sdk:a,cartId:g,lineId:l,quantity:i,metadata:f}){return await a.store.cart.updateLineItem(g,l,{quantity:i,metadata:f})}async function p({sdk:a,cartId:g,lineId:l,quantity:i,existingMeta:f}){const{is_gift:t,gift_from:r,gift_to:M,gift_message:h,...u}=f;return await a.store.cart.updateLineItem(g,l,{quantity:i,metadata:{...u,is_gift:!1,gift_from:"",gift_to:"",gift_message:""}})}function v({item:a,sdk:g,cartId:l,onSuccess:i,onError:f}){const t=a.metadata??{},r=t.is_gift===!0,M=!!t.gift_from||!!t.gift_to||!!t.gift_message,[h,u]=e.useState(!1),[G,w]=e.useState(!1),[q,b]=e.useState(!1),[C,d]=e.useState(null),[m,F]=e.useState({giftFrom:"",giftTo:"",giftMessage:""}),y=e.useCallback(()=>{F({giftFrom:t.gift_from??"",giftTo:t.gift_to??"",giftMessage:t.gift_message??""}),d(null),u(!0)},[t.gift_from,t.gift_to,t.gift_message]),T=e.useCallback(()=>{u(!1)},[]),k=e.useCallback(()=>{r||y()},[r,y]),L=e.useCallback((s,n)=>{F(_=>({..._,[s]:n}))},[]),B=e.useCallback(async()=>{d(null),w(!0);try{const s=m.giftFrom.trim(),n=m.giftTo.trim(),_=m.giftMessage.trim(),W={...t,is_gift:!0,...s&&{gift_from:s},...n&&{gift_to:n},..._&&{gift_message:_}};await c({sdk:g,cartId:l,lineId:a.id,quantity:a.quantity,metadata:W}),u(!1),i==null||i()}catch(s){const n=s instanceof Error?s:new Error("Failed to save gift");d(n.message),f==null||f(n)}finally{w(!1)}},[m,t,g,l,a.id,a.quantity,i,f]),R=e.useCallback(async()=>{b(!0),d(null);try{await p({sdk:g,cartId:l,lineId:a.id,quantity:a.quantity,existingMeta:t}),i==null||i()}catch(s){const n=s instanceof Error?s:new Error("Failed to remove gift");d(n.message),f==null||f(n)}finally{b(!1)}},[t,g,l,a.id,a.quantity,i,f]);return{isGift:r,hasDetails:M,giftMetadata:t,showModal:h,form:m,loading:G,removing:q,error:C,openModal:y,closeModal:T,handleCheck:k,handleSubmit:B,handleRemove:R,setFormField:L}}o.removeGiftMetadata=p,o.updateGiftMetadata=c,o.useGiftWrap=v,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "medusa-gift-wrap-logic",
+    "version": "1.0.0",
+    "description": "Reusable gift-wrap hook and service for Medusa storefronts. Manages per-line-item gift metadata (is_gift, gift_from, gift_to, gift_message) without any UI dependencies.",
+    "type": "module",
+    "main": "./dist/ui-library.umd.cjs",
+    "module": "./dist/ui-library.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/ui-library.js",
+            "require": "./dist/ui-library.umd.cjs",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc && vite build",
+        "preview": "vite preview"
+    },
+    "keywords": [
+        "medusa",
+        "gift-wrap",
+        "cart",
+        "ecommerce",
+        "react",
+        "hook"
+    ],
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    },
+    "dependencies": {
+        "@medusajs/js-sdk": "^2.11.2",
+        "@medusajs/types": "^2.11.2"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "@vitejs/plugin-react": "^4.0.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "typescript": "^5.0.0",
+        "vite": "^5.0.0",
+        "vite-plugin-dts": "^3.0.0"
+    }
+}