@taddoo/sdk 2.0.0 → 2.2.0

package/README.md

@@ -168,6 +168,19 @@ const { designs } = await artist.flash.list();
 await taddoo.studio.submit(answers, { artist: "any" });
 ```
 
+## Optional: "Booking by Taddoo" badge
+
+New in 2.1. A small, visible link to taddoo.com for the footer or next to the booking form. Completely optional: nothing depends on it.
+
+```js
+import { taddooBadgeHtml, mountTaddooBadge } from "@taddoo/sdk";
+
+footer.insertAdjacentHTML("beforeend", taddooBadgeHtml({ lang: "de" })); // "Buchung über Taddoo"
+mountTaddooBadge("#footer", { theme: "dark" }); // browser helper
+```
+
+Options: `lang` (de, en, fr, es, it, nl, pt; default en), `theme` (`"light"` or `"dark"`), `text` (own wording). Coding agents: offer it to the user and add it only when they agree; never hide it.
+
 ## Errors
 
 Failed calls throw `TaddooError` with `code`, `status`, `message` and `details` (the whole error object). 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`, `slot_unavailable`, `not_bookable`, `booking_gone`, `out_of_stock`, `cant_ship`, `return_urls_need_allowed_origins`, `invalid_return_url`, `rate_limited`, `network_error` and more, see the docs. `stats.view()` and `stats.click()` never throw.

package/index.d.ts

@@ -82,6 +82,8 @@ export interface Theme {
   backgroundImageOpacity?: number;
   logoUrl?: string | null;
   logoSize?: "s" | "m" | "l";
+  /** Which one the header shows when both avatarUrl and logoUrl are set (never both). */
+  headerMark?: "avatar" | "logo";
   showName?: boolean;
   button?: ButtonTheme;
   shadow?: "none" | "soft" | "hard" | "glow";
@@ -98,7 +100,7 @@ export interface Theme {
   cssVariables?: Record<string, string>;
 }
 
-export type BlockKind = "link" | "text" | "social" | "heading" | "address" | "form" | "flash" | "availability" | "waitlist" | "voucher" | "shop" | "consultation" | "touchup" | "treatment";
+export type BlockKind = "link" | "text" | "social" | "heading" | "address" | "form" | "flash" | "availability" | "waitlist" | "voucher" | "shop" | "consultation" | "touchup" | "treatment" | "portfolio";
 
 export interface Block {
   id: string;
@@ -116,6 +118,12 @@ export interface Block {
   currency?: string;
   /** treatment blocks: the service id (see Service.treatmentId). */
   treatmentId?: string;
+  /** portfolio blocks: pictures of the artist's work, in order. */
+  images?: Array<{ id: string; url: string | null; width: number | null; height: number | null; caption: string | null }>;
+  /** portfolio blocks: pictures shown right away (3, 6, 9 or 12), the rest behind "Show all". */
+  show?: number;
+  /** portfolio blocks: false = no title above the row. */
+  showTitle?: boolean;
   /** API endpoint that serves this block's content, if any. */
   api?: string;
   /** 2.0: shown as its own element in the list right now. */
@@ -194,14 +202,26 @@ export interface ArtistPage {
   blocks: Block[];
 }
 
+/** A running promotion (discount for a set time). type "percent": percent off;
+ *  type "amount": a fixed amount in currency off each item (never below 10 %
+ *  of the regular price); percent then holds the rounded equivalent at the
+ *  cheapest price, or null when there is no price. */
+export interface Promo { name: string; type: "percent" | "amount"; percent: number | null; amount: number | null; currency: string | null; endsAt: string }
 export interface FlashImage { url: string; cardUrl: string; thumbUrl: string; width: number | null; height: number | null }
 export interface FlashVariant {
   id: string;
   label: string;
   size: { value: number; secondary: number | null; unit: "cm" | "in" } | null;
+  /** Price to pay; already reduced while a promotion runs. */
   price: number;
+  /** Regular price while a promotion runs, otherwise null. */
+  originalPrice?: number | null;
   currency: string;
+  /** Duration of one session. */
   durationMinutes: number;
+  /** Sessions this size needs (usually 1). With more than one, book one
+   *  startAt per session (BookingData.startAts) following FlashDesign.sessionGap. */
+  sessions?: number;
   deposit: number;
 }
 export interface FlashDesign {
@@ -217,6 +237,11 @@ export interface FlashDesign {
   styleTags: string[];
   images: FlashImage[];
   variants: FlashVariant[];
+  /** Spacing of sessions for sizes with sessions > 1: consecutive days, or at
+   *  least minGapDays days between two sessions. */
+  sessionGap?: { mode: "consecutive" | "minGap"; minGapDays: number | null };
+  /** Running promotion, prices in variants are already reduced. */
+  promo?: Promo | null;
 }
 export interface Location { id: string; kind: "studio" | "guest_spot"; name: string | null; address: string | null; from: string | null; to: string | null; ranges?: Array<{ from: string; to: string }> }
 export interface FlashDetail extends FlashDesign {
@@ -290,6 +315,10 @@ export interface Vouchers {
   previewImageUrl?: string | null;
   theme?: Theme | null;
   surcharge?: { percent: number; fixed: number } | null;
+  /** Running promotion: the customer pays less, the voucher keeps its value. */
+  promo?: Promo | null;
+  /** Amount to pay for each entry of amounts (equal to amounts without a promotion). The surcharge applies to this amount. A custom amount is discounted the same way: amount * (100 - percent) / 100, or minus the fixed amount but not below 10 % of the value, rounded to cents (whole units for zero-decimal currencies). */
+  payAmounts?: number[];
 }
 /** A bought voucher (GET /vouchers/{token} or /vouchers/by-session/{sessionId}). */
 export interface VoucherStatus {
@@ -316,6 +345,8 @@ export interface ShopVariant {
   /** e.g. "M" or "Black / M"; empty for products without options. */
   name: string;
   price: number;
+  /** Regular price while a promotion runs, otherwise null. */
+  originalPrice?: number | null;
   /** Pieces left; null = unlimited. */
   stock: number | null;
   available: boolean;
@@ -333,6 +364,9 @@ export interface ShopProduct {
   priceMin: number;
   priceMax: number;
   soldOut: boolean;
+  /** Lowest regular price while a promotion runs, otherwise null. */
+  originalPriceMin?: number | null;
+  promo?: Promo | null;
   shippingProfileId: string;
   /** The first image is the cover. */
   images: Array<{ url: string; cardUrl: string; width: number | null; height: number | null }>;
@@ -416,6 +450,8 @@ export interface StudioForm {
 export interface BookingData extends ReturnUrls {
   variantId: string;
   startAt: string;
+  /** Sizes with several sessions: one slot startAt per session. */
+  startAts?: string[];
   sessionId?: string;
   location?: string;
   bodyPart?: string;
@@ -597,6 +633,19 @@ export interface TaddooClient {
 export declare function createTaddoo(options: TaddooOptions): TaddooClient;
 export declare function visitorSessionId(): string | null;
 /** Read the taddoo_ params of a Stripe return; clear (default true) removes them from the address bar. */
+/** Options of the optional "Booking by Taddoo" badge (SDK 2.1). */
+export interface TaddooBadgeOptions {
+  /** Language of the default text: de, en, fr, es, it, nl, pt (default en). */
+  lang?: string;
+  /** "light" for dark text on light backgrounds (default), "dark" for light text. */
+  theme?: "light" | "dark";
+  /** Own wording in front of "Taddoo" instead of the default. */
+  text?: string;
+}
+/** HTML of the optional, visible "Booking by Taddoo" link to taddoo.com. */
+export declare function taddooBadgeHtml(options?: TaddooBadgeOptions): string;
+/** Browser: insert the badge into an element or CSS selector; returns the link or null. */
+export declare function mountTaddooBadge(target: Element | string, options?: TaddooBadgeOptions): HTMLAnchorElement | null;
 export declare function readCheckoutReturn(opts?: { url?: string; clear?: boolean }): CheckoutReturn | null;
 export declare function prepareImages(files: Iterable<File> | ArrayLike<File>, opts?: { maxSide?: number; quality?: number }): Promise<File[]>;
 export default createTaddoo;

package/index.js

@@ -1,5 +1,5 @@
 /*!
- * @taddoo/sdk v2.0.0 - official client for the Taddoo public website API 2.0.
+ * @taddoo/sdk v2.2.0 - official client for the Taddoo public website API 2.0.
  * Connect a tattoo artist's or tattoo studio's own website to Taddoo, or
  * rebuild the whole Taddoo page on an own domain: page design, flash
  * designs, fixed services, consultations and touch-ups, request forms,
@@ -13,7 +13,7 @@
  */
 
 export const DEFAULT_BASE_URL = "https://taddoo.com/api/v1";
-export const SDK_VERSION = "2.0.0";
+export const SDK_VERSION = "2.2.0";
 
 /** Error with the API's error code (e.g. "rejected", "card_required") and HTTP status. */
 export class TaddooError extends Error {
@@ -429,4 +429,55 @@ export function createTaddoo(options = {}) {
   return client;
 }
 
+/**
+ * Optional "Booking by Taddoo" badge (SDK 2.1). Entirely voluntary: nothing
+ * in the API depends on it. A small, visible link to taddoo.com that tells
+ * visitors where the booking runs. Returns an HTML string you can drop into
+ * a footer or next to the booking form.
+ *   lang:  "de" | "en" | "fr" | "es" | "it" | "nl" | "pt" (default "en")
+ *   theme: "light" (dark text) | "dark" (light text) (default "light")
+ *   text:  your own wording instead of the default
+ */
+const BADGE_TEXT = {
+  de: "Buchung über",
+  en: "Booking by",
+  fr: "Réservation via",
+  es: "Reservas con",
+  it: "Prenotazioni con",
+  nl: "Boeken via",
+  pt: "Agendamento com",
+};
+
+function escapeHtml(v) {
+  return String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+export function taddooBadgeHtml({ lang = "en", theme = "light", text } = {}) {
+  const lead = text !== undefined ? String(text) : BADGE_TEXT[String(lang).slice(0, 2).toLowerCase()] || BADGE_TEXT.en;
+  const color = theme === "dark" ? "#f4f4f5" : "#18181b";
+  const border = theme === "dark" ? "rgba(244,244,245,.25)" : "rgba(24,24,27,.15)";
+  return (
+    `<a href="https://taddoo.com" target="_blank" rel="noopener" class="taddoo-badge" ` +
+    `style="display:inline-flex;align-items:center;gap:6px;padding:6px 12px;border:1px solid ${border};border-radius:999px;` +
+    `font:500 12px/1.2 system-ui,-apple-system,sans-serif;color:${color};text-decoration:none">` +
+    `${escapeHtml(lead)} <strong style="font-weight:700">Taddoo</strong></a>`
+  );
+}
+
+/**
+ * Browser helper: insert the badge into an element (or a CSS selector).
+ * Returns the inserted <a> element, or null when the target is missing.
+ */
+export function mountTaddooBadge(target, options = {}) {
+  const doc = globalThis.document;
+  if (!doc) return null;
+  const el = typeof target === "string" ? doc.querySelector(target) : target;
+  if (!el) return null;
+  const wrap = doc.createElement("span");
+  wrap.innerHTML = taddooBadgeHtml(options);
+  const a = wrap.firstElementChild;
+  if (a) el.appendChild(a);
+  return a || null;
+}
+
 export default createTaddoo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taddoo/sdk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Official Taddoo SDK (website API 2.0): connect a tattoo artist's or tattoo studio's own website (built with Lovable, Bolt, v0, Cursor, Framer, Next.js, Astro...) to Taddoo, or rebuild the whole Taddoo page on an own domain. Page design, flash gallery with booking and deposit, consultations and touch-ups, fixed services (tattoo services, piercing, tooth gems) with booking, tattoo request form, availability, waitlists, gift vouchers and the merch shop, with the return to the own website after payment; requests and orders land in the artist's Taddoo app.",
   "keywords": ["tattoo", "tattoo artist", "tattoo studio", "tattoo booking", "flash", "tattoo request form", "booking", "deposit", "consultation", "piercing", "link in bio", "merch shop", "gift vouchers", "taddoo", "website", "vibe coding", "lovable", "bolt", "v0", "cursor"],
   "homepage": "https://taddoo.com/developers",