@evlop/builder-api-client

A TypeScript/JavaScript client for the Evlop Builder API. It provides both static methods for account-level project (site) management and instance methods for managing a specific site's content, configuration, and assets.

Installation

npm install @evlop/builder-api-client

Usage

Configure the client

Call setConfig once, before using any static or instance methods, to set the access token, client ID, and (optionally) API base URL:

import BuilderApiClient from "@evlop/builder-api-client";

BuilderApiClient.setConfig({
  accessToken: "YOUR_ACCESS_TOKEN",
  clientId: "YOUR_CLIENT_ID",
  apiBaseUrl: "https://api.evlop.com", // optional, this is the default
});

Static methods (project/site management)

Static methods operate at the account level and are used to create, list, and manage sites.

const site = await BuilderApiClient.createProject({
  name: "My Site",
  domainName: "my-site",
});

const sites = await BuilderApiClient.getProjects();
const oneSite = await BuilderApiClient.getProject(site.id);

await BuilderApiClient.updateProject(site.id, { name: "New Name" });
await BuilderApiClient.activate(site.id);
await BuilderApiClient.deactivate(site.id);
await BuilderApiClient.deleteProject(site.id);

Instance methods (per-site content/config)

Create an instance scoped to a specific site to manage its pages, posts, collections, config, plugins, and more:

const client = new BuilderApiClient(site.id);

const pages = await client.getPages({ platform: "WEB" });
const page = await client.createPage({ title: "Home", slug: "/" });

API Reference

Configuration

| Method | Description | | --- | --- | | BuilderApiClient.setConfig(config) | Sets the static accessToken, clientId, and optional apiBaseUrl used by all requests. Must be called before using the client. |

Projects / Sites (static)

| Method | Description | | --- | --- | | BuilderApiClient.createProject({ name, domainName }) | Creates a new site. | | BuilderApiClient.getProjects() | Lists all sites. | | BuilderApiClient.getProject(siteId) | Fetches a single site by ID. | | BuilderApiClient.updateProject(siteId, updates) | Updates a site. | | BuilderApiClient.deleteProject(siteId) | Deletes a site. | | BuilderApiClient.updateActiveStatus(siteId, active) | Sets a site's active state. | | BuilderApiClient.activate(siteId) | Activates a site. | | BuilderApiClient.deactivate(siteId) | Deactivates a site. |

Instance lifecycle

| Method | Description | | --- | --- | | new BuilderApiClient(siteId, siteAccessToken?) | Creates a client scoped to a site. If siteAccessToken is provided, it is used instead of the static accessToken set via setConfig. | | client.destroy() | Deletes the site this client is scoped to. | | client.importData(data) | Imports configs, secrets, collections, pages, posts, and plugins into the site. | | client.exportData() | Exports the site's data. |

Pages

| Method | Description | | --- | --- | | client.getPages(filters) | Lists pages matching filters (defaults platform to "WEB"). | | client.createPage(pageData) | Creates a page. | | client.savePage(pageId, updates) | Updates a page. | | client.deletePage(pageId) | Deletes a page. |

Posts & Collections

| Method | Description | | --- | --- | | client.createCollection(collectionData) | Creates a collection. | | client.saveCollection(collectionId, collectionData) | Updates a collection. | | client.deleteCollection(collectionId) | Deletes a collection. | | client.getPosts(collectionHandle) | Lists all posts in a collection. | | client.getPost(collectionHandle, postId) | Fetches a single post. | | client.createPost(collectionHandle, postData) | Creates a post in a collection. | | client.savePost(collectionHandle, postId, postData) | Updates a post. | | client.deletePost(collectionHandle, postId) | Deletes a post. |

App configuration & secrets

| Method | Description | | --- | --- | | client.getAllConfig() | Fetches all config. | | client.saveAllConfig(config) | Saves all config; app config is routed through saveAppConfig and image fields are uploaded automatically. | | client.getConfig(configName) | Fetches a named config. | | client.saveConfig(configName, configData) | Saves a named config. | | client.deleteConfig(configName) | Deletes a named config. | | client.getAppConfig() | Fetches the app config. | | client.saveAppConfig(config) | Saves the app config. Any icon, logo, shopifyProductPlaceholder, shopifyCollectionPlaceholder, or splashImage field passed as a base64 data URL is automatically uploaded and replaced with its resulting URL. | | client.updateSecret(secretName, secretValue) | Sets a secret's value. |

Domains

| Method | Description | | --- | --- | | client.getDomainNames() | Lists domains for the site. | | client.addDomainName(domainName) | Adds a domain. | | client.updateDomainName(domainId, updates) | Updates a domain (name, primary, status). | | client.deleteDomainName(domainId) | Removes a domain. |

Plugins

| Method | Description | | --- | --- | | client.getPlugins() | Lists installed plugins. | | client.addPlugin(plugin) | Installs a plugin. | | client.updatePlugin(installationId, plugin) | Updates an installed plugin. | | client.deletePlugin(installationId) | Removes an installed plugin. |

Push notifications

| Method | Description | | --- | --- | | client.getPushNotifications(params) | Lists push notifications. | | client.broadcastPushNotification({ title, body, imageUrl, data, noSave, sendAt, topics, ... }) | Sends/schedules a push notification. |

File uploads

| Method | Description | | --- | --- | | client.getSignedUrl({ mimeType, fileName }) | Requests a signed upload URL for a file; generates a random file name if none is given. | | client.uploadFile({ content, mimeType, fileName }) | Uploads raw file content (Buffer/Uint8Array) via a signed URL and returns the resulting public URL. | | client.uploadBase64File(dataUrl, fileName) | Parses a base64 data URL and uploads it via uploadFile. |

App builds

| Method | Description | | --- | --- | | client.getBuilds() | Lists app builds. | | client.buildApp(buildOptions) | Triggers a new app build. buildOptions accepts platform ("ios" or "android"), displayName, version, versionCode, bundleIdentifier, icon, envVariables, secrets, noSave, and other arbitrary key: string fields. |

Cache

| Method | Description | | --- | --- | | client.clearCache(cacheKey) | Removes one or more cache keys. | | client.getCacheKeys(pattern) | Lists cache keys matching a pattern. | | client.getCacheAsList(cacheKey) | Fetches a cache entry stored as a list. | | client.removeValuesFromCacheList(listName, values) | Removes specific values from a cached list. |

Building

npm run build

This compiles ESM output to dist/esm, CommonJS output to dist/cjs, and type declarations to dist/types.

License

ISC