mb-web-sdk

TypeScript package to interact with the MagicBook API.

Installation

npm install @magiclabs.ai/mb-web-sdk

Usage

First, set up a callback to handle the asynchronous responses from the request you will make.

window.addEventListener("MagicBook", ((
  event: CustomEvent<MBEvent<unknown>>
) => {
  // Handle the event
  console.log(event.detail);
}) as EventListener);

⚠️ If the server takes an unexpectedly long time to respond, the SDK will send a timeout and a final event.

the events you will receive will have three props

{
  "eventType": "project.autofill", // optional
  "eventName": "surfaces.autofill"
  "request": {...}
  "result": {...}
}

Create a MagicBook API instance

const api = new MagicBookAPI({
  apiKey: string,
  apiHost? string, // Default to api.prod.magiclabs-aurora.io
  mock?: boolean, // Default to false
  debugMode?: boolean //Default to false for non production apiHosts
});

Once you receive the ws event with result

{
  "areConnectionsOpen": true,
  "hasReachedMaxReconnectionAttempts": false
}

You are ready to go!

hasReachedMaxReconnectionAttempts becomes true once a socket has exhausted its automatic reconnection attempts, and is reset to false as soon as a connection succeeds again. Use it to surface a terminal connection error to the user or to trigger a manual reconnect.

The WS surface is exposed under api.ws:

• api.ws.status — current { areConnectionsOpen, hasReachedMaxReconnectionAttempts }.
• api.ws.open() — open (or reopen) both sockets. One-shot: if the connection fails it does not trigger the SDK's automatic retry budget — the promise resolves with areConnectionsOpen: false and hasReachedMaxReconnectionAttempts: true, leaving spacing of further attempts up to you.
• api.ws.disconnect() — close both sockets and disable auto-retry. Returns the new status synchronously; the underlying close completes shortly after.

If the WS connection fails to reconnect, you can manually reconnect it with

await api.ws.open();

This promise will return the same response as the ws event above.

Closing the connection on idle

If the user goes idle (e.g. no activity for several minutes, tab hidden, etc.) and you want to free the socket without the SDK auto-reconnecting, call

api.ws.disconnect();

This closes both sockets, stops the heartbeat and TTL timers, and disables auto-retry. Call await api.ws.open() to come back online — the internal retry budget is reset, so reconnects start fresh.

let idleTimer: ReturnType<typeof setTimeout> | undefined;
const IDLE_MS = 5 * 60_000;

const goIdle = () => api.ws.disconnect();
const resetIdleTimer = () => {
  clearTimeout(idleTimer);
  idleTimer = setTimeout(goIdle, IDLE_MS);
};

const wakeUp = async () => {
  resetIdleTimer();
  if (!api.ws.status.areConnectionsOpen) await api.ws.open();
};

["mousemove", "keydown", "pointerdown"].forEach((evt) =>
  window.addEventListener(evt, wakeUp),
);
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") goIdle();
  else wakeUp();
});

resetIdleTimer();

Example: smart retry with exponential backoff

The SDK's built-in retries use short, fixed-step delays and stop after a fixed number of attempts. For long outages you usually want to keep trying, but space attempts further apart so you don't hammer the server. The snippet below waits for hasReachedMaxReconnectionAttempts, then loops api.ws.open() with exponential backoff capped at one minute, plus jitter so multiple clients recovering from the same outage don't retry in lockstep.

Each call to api.ws.open() is a single attempt — it does not fall back to the SDK's automatic retry budget. If it returns areConnectionsOpen: false, you are responsible for spacing the next attempt — which is what the loop below does.

const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));

window.addEventListener("MagicBook", (async (event: CustomEvent<MBEvent<unknown>>) => {
  if (event.detail.eventName !== "ws") return;
  const { hasReachedMaxReconnectionAttempts } = event.detail.result;
  if (!hasReachedMaxReconnectionAttempts) return;

  for (let attempt = 0; ; attempt++) {
    const backoff = Math.min(60_000, 1000 * 2 ** attempt);
    await wait(backoff * Math.random()); // full jitter
    const { areConnectionsOpen } = await api.ws.open();
    if (areConnectionsOpen) return;
  }
}) as EventListener);

The await chain serialises retries, so re-entry from later ws events is naturally bounded — if a loop is already running, the next event's loop will succeed on its first api.ws.open() call (because the first loop got us connected) and exit. In a component, capture the listener reference and remove it on unmount, and gate the loop body on a cancelled flag so an in-flight loop on a stale api instance can be stopped.

Photos

Analyze

To analyze an array of photos, call the photos.analyze function. Once ready, an event will be sent to the listener you created earlier.

await api.photos.analyze(
  photos.map((photo) => ({
    id: photo.handle, // string
    width: photo.width, // number
    height: photo.height, // number
    orientation: photo.orientation, // number
    url: photo.url, // string
    encryptId, // optional string
    timestamp: photo.timestamp, // optional string
    dateTimeDigitize: photo.dateTimeDigitize, // optional string
    dateTimeOriginal: photo.dateTimeOriginal, // optional string
    dateTime: photo.dateTime, // optional string
    make: photo.make, // optional string
    model: photo.model, // optional string
    filename: photo.filename, // optional string
  }))
);

⚠️ If more than 5% of the returned images are not selected, you will receive a warning.photo-access-deprecated event before the final event.

Projects

Autofill Options

To get the autofill options, call the projects.autofillOptions function with the image count of the project.

await api.projects.autofillOptions(imageCount);

Autofill

To create a project with autofill, call the projects.autofill function. Once ready, a project event will be sent, followed by surface events, to the listener you created earlier.

await api.projects.autofill({
  title: "My Book", // optional
  subtitle: "A collection of photos", // optional
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  images: [...],
});

Restyle

To create a project with restyle, call the projects.restyle function. Once ready, a project event will be sent, followed by surface events, to the listener you created earlier.

await api.projects.restyle({
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  images: [...],
  surfaces: [surface1, surface2, ...]
});

Resize

To resize a project, call the projects.resize function. Once ready, a project event will be sent, followed by surface events, to the listener you created earlier.

await api.projects.resize({
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  targetBookFormat: {...}, // optional - same schema as bookFormat
  images: [...],
  surfaces: [surface1, surface2, ...]
});

Surfaces

Shuffle

To create a surface with shuffle, call the surfaces.shuffle function. Once ready, an event will be sent to the listener you created earlier.

await api.surfaces.shuffle({
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  images: [...],
  surfaces: [surface1, surface2] // array of surfaces max length 2
}, {
  keepImageSequence?: boolean // default to false
});

AutoAdapt

To create a surface with autoAdapt, call the surfaces.autoAdapt function. Once ready, an event will be sent to the listener you created earlier.

await api.surfaces.autoAdapt({
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  images: [...],
  surfaces: [surface1, surface2] // array of surfaces max length 2
});

Suggest

To create a surface with suggest, call the surfaces.suggest function. Once ready, an event will be sent to the listener you created earlier.

await api.surfaces.suggest({
  designMode: "automatic",
  occasion: "birthday",
  style: "modern",
  imageFilteringLevel: "best",
  imageDensityLevel: "high",
  embellishmentLevel: "high",
  bookFormat: {
    pageType: "Standard Pages", // optional
    skuPageRange: [min, max], // optional
    startFromLeftSide: true, // default to false
    targetPageRange: [20, 40],
    page: {
      width: 8,
      height: 11,
    },
    cover: {
      width: 8,
      height: 11,
    },
    coverWrap: {
      top: 0.75,
      right: 0.75,
      bottom: 0.75,
      left: 0.75
    }, // optional
    bleed: {
      top: 0.125,
      right: 0.0625,
      bottom: 0.125,
      left: 0.0625
    } // optional
  },
  images: [...],
  surfaces: [surface1, surface2] // array of surfaces max length 2
});

Image Densities

To retrieve the image densities, call the imageDensities function.

await api.imageDensities(sku: string, imageCount: number, imageFilteringLevel: string);

Styles

To list the active style in the library, call the styles.list function.

await api.styles.list(); //default qs: ?active=false

To retrieve a specific style by DG_XXXX, call the styles.retrieve function.

await api.styles.retrieve("DG_XXXX");

Usage as script

For example using express convert to static route

app.use(
  "/scripts/mb-web-sdk",
  express.static(__dirname + "/node_modules/@magiclabs.ai/mb-web-sdk")
);

<!DOCTYPE html>
<html>
  <head>
    <script
      type="text/javascript"
      src="/scripts/mb-web-sdk/index.iife.js"
    ></script>
  </head>
  <script type="text/javascript">
    const api = new MagicLabs.MagicBookAPI({...})

    window.addEventListener("MagicBook", async (event) => {
      if (event.detail.eventName === 'ws' && event.detail.result.areConnectionsOpen) {
        await makeBookRequest();
      }
    });

    async function makeBookRequest() {
      const test = await api.photos.analyze([
        {
          id: "1234",
          orientation: 0,
          width: 100,
          height: 100,
          url: "https://...",
        },
      ]);
    }
  </script>
</html>

Example

To see the MagicBook client in action, run the following commands (make sure you created a .env file before building):

npm run build
cd example
npm i
npm run dev