@taddoo/sdk 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Official SDK for the **Taddoo public website API**. Connect a tattoo artist's or tattoo studio's own website to [Taddoo](https://taddoo.com), the app tattoo artists use for requests, bookings, deposits, consent forms and bookkeeping.
 
-With a few lines the website shows the artist's **flash** (designs, sizes, prices, free slots, booking with deposit via Stripe), their **tattoo request form** (every question exactly as configured, with reference images), **fixed services** like a booking menu (tattoo services such as "small tattoo, 1 h, CHF 250" or "medium tattoo, 4 h, 300 to 500", piercing, tooth gems, each with price, duration, deposit and reference images), **availability** (free days, guest spots), **waitlists** and **gift vouchers**, all in the website's own design. Everything a client sends lands in the artist's Taddoo app on iPhone, iPad, Android and Mac: requests as projects with a push notification, bookings in the calendar.
+With a few lines the website shows the artist's **flash** (designs, sizes, prices, free slots, booking with deposit via Stripe), their **tattoo request form** (every question exactly as configured, with reference images), **fixed services** like a booking menu (tattoo services such as "small tattoo, 1 h, CHF 250" or "medium tattoo, 4 h, 300 to 500", piercing, tooth gems, each with price, duration, deposit and reference images), **availability** (free days, guest spots), **waitlists**, **gift vouchers** and the **merch shop** (shirts, hoodies, prints with sizes, stock, shipping per country and checkout via Stripe), all in the website's own design. Everything a client sends lands in the artist's Taddoo app on iPhone, iPad, Android and Mac: requests as projects with a push notification, bookings in the calendar.
 
 - Zero dependencies, ESM, TypeScript types included
 - Browser, Node 18+, Deno, Bun, edge runtimes
@@ -77,6 +77,19 @@ if (res.status === "payment_required") window.location.href = res.checkoutUrl; /
 
 Designs with `bookingMode: "request"` use `taddoo.flash.request(id, { variantId, name, email, wishDate })` instead.
 
+## Merch shop
+
+```js
+const shop = await taddoo.shop.get();                    // products, variants, stock, shipping profiles
+const cart = [{ variantId: shop.products[0].variants[0].id, quantity: 1 }];
+const res = await taddoo.shop.checkout({ items: cart, country: "CH" });
+localStorage.setItem("lastOrder", res.order.token);
+window.location.href = res.checkoutUrl;                  // Stripe: address, phone, payment
+// later: await taddoo.shop.order(token) -> { status: "paid" | "shipped" | ..., number }
+```
+
+Shipping works like on Etsy: each product has a shipping profile with rates per country (`"EU"` and `"*"` for the rest of the world), the piece with the highest first-item price pays it once, every further piece its additional price. The checkout computes the real totals and reserves the stock for 30 minutes; `out_of_stock` (409) tells you which `variantId` has how many pieces `available`.
+
 ## Questions and answers
 
 Every question has `id`, `label`, `required` and `input.type`:
@@ -95,7 +108,7 @@ await taddoo.studio.submit(answers, { artist: "any" });
 
 ## Errors
 
-Failed calls throw `TaddooError` with `code`, `status` and `message`. For `code === "rejected"` the message is already translated for the visitor: show it as is. Other codes: `card_required`, `account_inactive`, `page_not_live`, `origin_not_allowed`, `session_required`, `books_closed`, `rate_limited`, `network_error` and more, see the docs.
+Failed calls throw `TaddooError` with `code`, `status` and `message`. For `code === "rejected"` the message is already translated for the visitor: show it as is. Other codes: `card_required`, `account_inactive`, `page_not_live`, `origin_not_allowed`, `session_required`, `books_closed`, `out_of_stock`, `cant_ship`, `rate_limited`, `network_error` and more, see the docs.
 
 ## Server-side use
 

package/index.d.ts

@@ -34,7 +34,7 @@ export interface Theme { preset: string; accent: string; background: string; mod
 
 export interface Block {
   id: string;
-  kind: "link" | "text" | "social" | "heading" | "address" | "form" | "flash" | "availability" | "waitlist" | "voucher" | "consultation" | "touchup" | "treatment";
+  kind: "link" | "text" | "social" | "heading" | "address" | "form" | "flash" | "availability" | "waitlist" | "voucher" | "shop" | "consultation" | "touchup" | "treatment";
   title: string;
   url: string | null;
   imageUrl: string | null;
@@ -44,6 +44,7 @@ export interface Block {
   handles?: Record<string, string | null>;
   formId?: string;
   amounts?: number[];
+  customAmount?: { min: number; max: number } | null;
   currency?: string;
   /** API endpoint that serves this block's content, if any. */
   api?: string;
@@ -117,12 +118,15 @@ export interface Question { id: string; kind: string; label: string; hint: strin
 export interface Form { id: string; title: string; url: string | null; intro: string | null; thanks: string | null; acceptsRequests: boolean; questions: Question[] }
 export type Answers = Record<string, string | number | boolean | Array<string | number>>;
 
+export interface FreeTime { full: boolean; windows: Array<{ from: string; to: string }> }
 export interface Availability {
   books: Books;
   timezone: string;
   horizonDays: number;
   freeDays: string[];
-  studios: Array<{ id: string; name: string; address: string | null; freeDays: string[] }>;
+  /** Free hours per free day in local time; empty when the artist hides them. */
+  freeTimes: Record<string, FreeTime>;
+  studios: Array<{ id: string; name: string; address: string | null; freeDays: string[]; freeTimes: Record<string, FreeTime> }>;
   guestSpots: Array<{ id: string; name: string; address: string | null; from: string; to: string }>;
   timeOff: Array<{ from: string; to: string }>;
 }
@@ -137,7 +141,52 @@ export interface Waitlist {
   fields: Record<string, unknown>;
   sizeUnit: "cm" | "in";
 }
-export interface Vouchers { available: boolean; url: string | null; amounts: number[]; currency: string; validityMonths: number | null; intro: string | null; terms: string | null }
+export interface Vouchers { available: boolean; url: string | null; amounts: number[]; /** Own whole amount allowed between min and max, or null. */ customAmount: { min: number; max: number } | null; currency: string; validityMonths: number | null; intro: string | null; terms: string | null }
+
+export interface ShopVariant {
+  id: string;
+  /** e.g. "M" or "Black / M"; empty for products without options. */
+  name: string;
+  price: number;
+  /** Pieces left; null = unlimited. */
+  stock: number | null;
+  available: boolean;
+}
+export interface ShopProduct {
+  id: string;
+  slug: string;
+  /** Product page on taddoo.com. */
+  url: string;
+  title: string;
+  description: string | null;
+  categoryId: string | null;
+  /** Name of the option, e.g. "Size"; null = no options. */
+  optionName: string | null;
+  priceMin: number;
+  priceMax: number;
+  soldOut: boolean;
+  shippingProfileId: string;
+  /** The first image is the cover. */
+  images: Array<{ url: string; cardUrl: string; width: number | null; height: number | null }>;
+  variants: ShopVariant[];
+}
+/** Shipping like on Etsy: country is an ISO code, "EU" or "*" (rest of the world); the most specific rate applies. The piece with the highest first price pays first once, every other piece its additional. */
+export interface ShopRate { country: string; first: number; additional: number }
+export interface ShopShippingProfile { id: string; deliveryNote: string | null; rates: ShopRate[] }
+export interface Shop {
+  /** false: no shop, no product yet or online payments not set up. */
+  available: boolean;
+  url: string | null;
+  currency: string;
+  intro: string | null;
+  terms: string | null;
+  /** Fee the customer pays on top of items plus shipping (percent as a fraction, e.g. 0.049); null when the artist pays it. */
+  surcharge: { percent: number; fixed: number } | null;
+  categories: Array<{ id: string; name: string }>;
+  products: ShopProduct[];
+  shippingProfiles: ShopShippingProfile[];
+}
+export interface ShopOrderStatus { status: "pending" | "paid" | "shipped" | "canceled" | "refunded"; number: number; email: string | null }
 
 export interface Studio {
   type: "studio";
@@ -206,11 +255,18 @@ export interface TaddooClient {
     join(id: string, data: { name: string; email: string; phone?: string; instagram?: string; preferredContact?: "email" | "instagram" | "whatsapp" | "sms"; wish?: string; bodyPart?: string; size?: number; sizeSecondary?: number }, opts?: { images?: File[] }): Promise<{ status: "joined" }>;
   };
   /** Fixed services: tattoo services, piercing, tooth gems, custom. */
-  services(): Promise<{ services: Service[] }>;
+  services(opts?: { locale?: string }): Promise<{ services: Service[] }>;
   vouchers: {
     get(): Promise<Vouchers>;
     checkout(data: { amount: number; name: string; email: string; recipient?: string; message?: string }): Promise<{ checkoutUrl: string }>;
   };
+  /** Merch shop: products, cart checkout via Stripe, order status. */
+  shop: {
+    get(opts?: CallOptions): Promise<Shop>;
+    /** country: ISO code of the delivery address. Errors: out_of_stock / changed (409, with variantId and available), cant_ship (422). */
+    checkout(data: { items: Array<{ variantId: string; quantity: number }>; country: string }, opts?: CallOptions): Promise<{ checkoutUrl: string; order: { number: number; token: string } }>;
+    order(token: string, opts?: CallOptions): Promise<ShopOrderStatus>;
+  };
   studio: {
     get(): Promise<Studio>;
     form(): Promise<StudioForm>;

package/index.js

@@ -1,8 +1,8 @@
 /*!
- * @taddoo/sdk v1.0.0 - official client for the Taddoo public website API.
+ * @taddoo/sdk v1.1.0 - official client for the Taddoo public website API.
  * Connect a tattoo artist's or tattoo studio's own website to Taddoo:
- * flash designs, fixed services, request forms, availability, waitlists and
- * gift vouchers.
+ * flash designs, fixed services, request forms, availability, waitlists,
+ * gift vouchers and the merch shop.
  * Requests and bookings land in the artist's Taddoo app.
  * Docs: https://taddoo.com/developers  ·  Guide for coding agents: https://taddoo.com/developers/llms.txt
  * No dependencies. Works in browsers, Node 18+, Deno, Bun and edge runtimes.
@@ -11,7 +11,7 @@
  */
 
 export const DEFAULT_BASE_URL = "https://taddoo.com/api/v1";
-export const SDK_VERSION = "1.0.0";
+export const SDK_VERSION = "1.1.0";
 
 /** Error with the API's error code (e.g. "rejected", "card_required") and HTTP status. */
 export class TaddooError extends Error {
@@ -219,6 +219,17 @@ export function createTaddoo(options = {}) {
       /** { amount, name, email, recipient?, message? } -> { checkoutUrl } */
       checkout: (data, o = {}) => request("POST", "/vouchers/checkout", { ...o, json: data }),
     },
+    shop: {
+      /** Merch shop: { available, url, currency, intro, terms, surcharge, categories, products, shippingProfiles }. */
+      get: (o = {}) => request("GET", "/shop", o),
+      /**
+       * Pay a cart: { items: [{ variantId, quantity }], country } ->
+       * { checkoutUrl, order: { number, token } }. Redirect to checkoutUrl (Stripe).
+       */
+      checkout: (data, o = {}) => request("POST", "/shop/checkout", { ...o, json: data }),
+      /** Status of an order from checkout: { status, number, email }. */
+      order: (token, o = {}) => request("GET", `/shop/orders/${encodeURIComponent(token)}`, o),
+    },
     studio: {
       /** Studio key only: studio page with artists, opening hours and flash. */
       get: () => request("GET", "/studio", { artist: null }),

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@taddoo/sdk",
-  "version": "1.0.0",
-  "description": "Official Taddoo SDK: connect a tattoo artist's or tattoo studio's own website (built with Lovable, Bolt, v0, Cursor, Framer, Next.js, Astro...) to Taddoo. Flash gallery with booking and deposit, fixed services (tattoo services, piercing, tooth gems) with prices, tattoo request form, availability, waitlists and gift vouchers; requests land in the artist's Taddoo app.",
-  "keywords": ["tattoo", "tattoo artist", "tattoo studio", "tattoo booking", "flash", "tattoo request form", "booking", "deposit", "link in bio", "taddoo", "website", "vibe coding", "lovable", "bolt", "v0", "cursor"],
+  "version": "1.1.0",
+  "description": "Official Taddoo SDK: connect a tattoo artist's or tattoo studio's own website (built with Lovable, Bolt, v0, Cursor, Framer, Next.js, Astro...) to Taddoo. Flash gallery with booking and deposit, fixed services (tattoo services, piercing, tooth gems) with prices, tattoo request form, availability, waitlists, gift vouchers and the merch shop; requests and orders land in the artist's Taddoo app.",
+  "keywords": ["tattoo", "tattoo artist", "tattoo studio", "tattoo booking", "flash", "tattoo request form", "booking", "deposit", "link in bio", "merch shop", "taddoo", "website", "vibe coding", "lovable", "bolt", "v0", "cursor"],
   "homepage": "https://taddoo.com/developers",
   "license": "MIT",
   "author": "Taddoo AG <hello@tattoomii.com> (https://taddoo.com)",