MartEye Studio JavaScript SDK (@marteye/studiojs)

This library is a JavaScript SDK that allows you to easily integrate with MartEye Studio's API. It provides methods to interact with various resources, manage data, and leverage the powerful features offered by MartEye Studio.

Installation

You can install the library using npm or yarn:

Using npm:

npm install @marteye/studiojs

Using yarn:

yarn add @marteye/studiojs

Usage

Importing the Library

Using ES Modules:

import StudioJS from "@marteye/studiojs";

Or using CommonJS:

let StudioJS = require("@marteye/studiojs");

Initializing the SDK

Before using the library, initialize it with your API key. For more information on obtaining an API key, please contact your MartEye representative.

let studioClient = StudioJS({
  apiKey: "YOUR_API_KEY_HERE",
});

Files and media uploads

StudioJS includes file upload helpers on studio.files. They reuse the same Studio API key or Firebase ID token that initialized the SDK, so callers do not pass a second upload token.

import Studio from "@marteye/studiojs";

const studio = Studio({
  apiKey: "YOUR_STUDIO_TOKEN_OR_API_KEY",
});

Select production or staging uploads

The SDK picks the correct Studio upload endpoint from your project environment. You do not configure upload service URLs yourself.

Resolution priority:

1. EXPO_PUBLIC_STUDIO_ENV
2. NEXT_PUBLIC_STUDIO_ENV
3. STUDIO_ENV
4. NODE_ENV

Supported values:

• production or prod
• staging, stage, development, or dev

Examples:

# Next.js browser/server bundle
NEXT_PUBLIC_STUDIO_ENV=staging

# Expo browser/native bundle
EXPO_PUBLIC_STUDIO_ENV=staging

# Node.js
STUDIO_ENV=staging

Upload a lot file

Pass a File or Blob-like object. The SDK chooses a single or multipart upload automatically; large files are uploaded as multipart without changing this API.

await studio.files.upload({
  marketId: "market_123",
  saleId: "sale_123",
  lotId: "lot_123",
  attributeId: "media",
  file,
});

Override the destination file name when needed:

await studio.files.upload({
  marketId: "market_123",
  saleId: "sale_123",
  lotId: "lot_123",
  attributeId: "media",
  file,
  fileName: "front-view.jpg",
});

Force multipart only when you need to:

await studio.files.upload({
  marketId: "market_123",
  saleId: "sale_123",
  lotId: "lot_123",
  attributeId: "media",
  file,
  strategy: "multipart",
  onProgress(progress) {
    console.log(progress.bytesUploaded, progress.totalBytes);
  },
});

Upload from a URL

Pass sourceUrl instead of file. The URL must be directly fetchable; redirecting URLs are rejected.

await studio.files.upload({
  marketId: "market_123",
  saleId: "sale_123",
  lotId: "lot_123",
  attributeId: "media",
  sourceUrl: "https://example.com/media/photo.jpg",
});

Optional fileName overrides the name inferred from the URL. Pass a file name when you want to immediately set the uploaded file on a lot attribute.

await studio.files.upload({
  marketId: "market_123",
  saleId: "sale_123",
  lotId: "lot_123",
  attributeId: "media",
  sourceUrl: "https://example.com/media/photo.jpg",
  fileName: "catalogue-photo.jpg",
});

Set the uploaded file on a lot

upload() stores the file and returns its asset id and URLs. Attach it to a lot by updating the attribute afterwards:

const upload = await studio.files.upload({
  marketId,
  saleId,
  lotId,
  attributeId: "media",
  file,
});

await studio.lots.update(marketId, saleId, lotId, {
  attributes: {
    media: {
      id: upload.assetId,
      fileName: file.name,
      fileType: file.type,
      url: upload.expected.original?.url ?? "",
    },
  },
});

Upload to a custom path

For non-lot files, pass a market-prefixed path and choose transform or direct mode.

await studio.files.upload({
  marketId: "market_123",
  mode: "transform",
  path: "market_123/users/user_123/avatar.jpg",
  file,
});

URL uploads support lot and transform uploads:

await studio.files.upload({
  marketId: "market_123",
  mode: "transform",
  path: "market_123/users/user_123",
  sourceUrl: "https://example.com/avatar.jpg",
  fileName: "avatar.jpg",
});

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you have suggestions or improvements.

License

MIT