oneentry

v1.0.166

Published

4 days ago

OneEntry NPM package

Downloads

1,610

0High
0Medium
0Low

oneentry

OneEntry SDK

OneEntry SDK is an SDK that provides an easy way to interact with the OneEntry API.

Official Site

Visit the official OneEntry website at https://oneentry.cloud to learn more about the OneEntry Platform.

Sign Up

To get started with OneEntry, sign up for an account at https://account.oneentry.cloud/authentication/register.

Installation

To install the OneEntry SDK in your project, run the following command:

npm install oneentry

Quick Start with CLI

After installation, run the interactive setup tool to generate a working example and see live data from your project:

npx oneentry

It will ask for your project URL and API token, generate an example.mjs file, and optionally run it immediately — printing admins, pages and products to the console.

Get Started

To use the OneEntry SDK in your project, import the defineOneEntry function:

import { defineOneEntry } from 'oneentry'

const config = {
    token: 'your-app-token',
}
const {
    Admins,
    AttributesSets,
    AuthProvider,
    Blocks,
    Discounts,
    Events,
    FileUploading,
    Filters,
    Forms,
    FormData,
    GeneralTypes,
    IntegrationCollections,
    Locales,
    Menus,
    Orders,
    Pages,
    Payments,
    Products,
    ProductStatuses,
    Search,
    Sitemap,
    Subscriptions,
    System,
    Templates,
    TemplatePreviews,
    UserActivity,
    Users,
    WS,
} = defineOneEntry('your-url', config)

const config = {
    token: 'your-app-token',
}
const api = defineOneEntry('your-url', config)

Config

The second parameter of the constructor takes the 'config'. It contains the following values:

'token' - Set the token key if your project secure "Security API Token". If you are using certificate protection, do not pass this variable. You can read more about the security of your project here.
'langCode' - Set the "langCode" to set the default language. By specifying this parameter once, you don't have to pass the langCode to the methods ONEENTRY API. If you have not passed the default language, it will be set "en_US".
'guestId' - Optional guest identifier sent as the "x-guest-id" header on unauthenticated requests. It enables guest cart / wishlist / activity flows. In the browser, if you omit it, the SDK generates a stable id and persists it in localStorage. On the server you must pass a per-visitor "guestId" (or call "setGuestId"): the SDK never auto-generates a server id, to avoid sharing one guest across visitors. The header is omitted once a user is authenticated.
'deviceMetadata' - Optional device-metadata string sent as the "x-device-metadata" header instead of the fingerprint the SDK computes from the current environment. The API binds refresh tokens to this header, so a server that issues tokens on behalf of a browser (for example, an OAuth code exchange keeping the client secret server-side) must pass the browser's string here — otherwise the issued refresh token is bound to the server's fingerprint and cannot be refreshed from the browser. Obtain the string in the browser via "getDeviceMetadata()" and set/clear it at runtime via "setDeviceMetadata".
'traficLimit' - Some methods use more than one request to the CMS so that the data you receive is complete and easy to work with. Pass the value "true" for this parameter to save traffic and decide for yourself what data you need. The default value "false".
'auth' - An object with authorization settings. By default, the SDK is configured to work with tokens inside the user's session and does not require any additional work from you. At the same time, the SDK does not store the session state between sessions. If you are satisfied with such settings, do not pass the variable 'auth' at all.

The 'auth' contains the following settings:

'refreshToken' - The user's refresh token. Transfer it here from the repository to restore the user's session during initialization.
'saveFunction' - A function that works with the update refresh token. If you want to store the token between sessions, for example in local storage, pass a function here that does this. The function must accept a parameter to which the string with the token will be passed.
'customAuth' - If you want to configure authorization and work with tokens yourself, set this flag to true. If you want to use the sdk settings, set it to false or do not transfer it at all.

An example of a configuration with token protection and automatic authentication that stores state between sessions

const tokenFunction = (token) => {
    localStorage.setItem('refreshToken', token)
}

const api = defineOneEntry('https://my-project.oneentry.cloud', {
    token: 'my-token',
    langCode: 'en_US',
    auth: {
        refreshToken: localStorage.getItem('refreshToken'),
        saveFunction: tokenFunction,
        providerMarker: 'email',
    },
})

An example of a configuration that is protected with a certificate allows you to configure the authorization system yourself and saves data on requests.

const api = defineOneEntry('https://my-project.oneentry.cloud', {
    langCode: 'en_US',
    traficLimit: true,
    auth: {
        customAuth: true,
        refreshToken: localStorage.getItem('refreshToken'),
        providerMarker: 'email',
    },
})

If you have chosen to configure tokens yourself, you can pass the token to the method as follows. The intermediate method allows you to pass an access token to the request. Then call the required method. This method (setAccessToken) should not be called if the method does not require user authorization.

const user = api.Users.setAccessToken('my.access.token').getUser()

If you chose token protection to ensure connection security, just pass your token to the function as an optional parameter.

You can get a token as follows

Log in to your personal account
Go to the "Projects" tab and select a project
Go to the "Access" tab
Set the switch to "Security API Token"
Log in to the project, go to the settings section and open the token tab
Get and copy the token of your project

You can also connect a tls certificate to protect your project. In this case, do not pass the "token" at all. When using the certificate, set up a proxy in your project. Pass an empty string as an url parameter. Learn more about security

const saveTokenFromLocalStorage = (token) => {
    localStorage.setItem('refreshToken', token)
}

const api = defineOneEntry('your-url', {
    token: 'my-token',
    langCode: 'my-langCode',
    auth: {
        customAuth: false,
        userToken: 'rerfesh.token',
        providerMarker: 'email',
        saveFunction: saveTokenFromLocalStorage,
    },
})

TypeScript Types

All public interfaces and types are re-exported from the package root, so deep paths are not needed:

import type { IAttributeSchemaItem, IAttributeSetsEntity } from 'oneentry'

The same set is also available from a types-only entry point, if you prefer to keep type imports separate from the runtime import:

import type { IProductsEntity, IUserEntity } from 'oneentry/types'

Deep imports such as oneentry/dist/attribute-sets/attributeSetsInterfaces still work and remain supported.

Optional Features

API Response Validation

OneEntry SDK supports optional validation of API responses using Zod. This feature is disabled by default and can be enabled for development or critical operations.

Zod and the response schemas are loaded on demand, the first time a response actually has to be validated. Leaving validation off — the default — keeps them out of the code your app loads. Socket.io is deferred the same way, until the first WS.connect().

Together that means a project calling a single SDK method loads about 43 kB minified (9.7 kB gzip) instead of 536 kB, with Zod, the schemas and Socket.io landing in chunks that are never requested. The SDK is published as both CommonJS and ESM (sideEffects: false), so bundlers can tree-shake the rest.

Attribute Values

IAttributeValue.value is typed unknown — its shape is decided by type at runtime. The trap is files: an image/file attribute holding one file has its value unwrapped to the file object itself, while several files and every groupOfImages stay an array. Reading the wrong shape is not a compile error, it is a silently missing image. Read files through the helpers instead:

import { defineOneEntry, getAttributeFile, getAttributeFiles } from 'oneentry'

const { Pages } = defineOneEntry('your-url', { token: 'your-app-token' })
const page = await Pages.getPageByUrl('catalog')

// Same call whether the attribute holds one file or a gallery.
const images = getAttributeFiles(page.attributeValues.gallery) // IAttributeFile[]
const cover = getAttributeFile(page.attributeValues.cover) // IAttributeFile | null
const blurDataURL = cover?.previewLink?.default?.[0]

Also exported: getAdditionalFields(attr) for an attribute's nested fields as a marker map, the type guards isFileAttribute, isStringAttribute, isNumberAttribute, isListAttribute, the file type IAttributeFile, and ITypedAttributeValue — IAttributeValue as a discriminated union over type, to annotate with where you want the compiler to enforce the shape.

Time Intervals

Attributes of type timeInterval return a compact recurrence rule (an anchor date, daily time ranges and repeat flags), not a ready list of slots. The SDK does not expand it eagerly — a single attribute can materialize into megabytes of slots — so resolve it on demand with expandAttributeTimeIntervals, passing the window you actually render:

import { defineOneEntry, expandAttributeTimeIntervals } from 'oneentry'

const { Pages } = defineOneEntry('your-url', { token: 'your-app-token' })
const page = await Pages.getPageByUrl('booking')

const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
    from: '2025-04-01',
    to: '2025-04-30',
})
// [['2025-04-14T09:00:00.000Z', '2025-04-14T10:00:00.000Z'], …]

Also exported: expandTimeIntervals(schedule, window) for a single schedule (e.g. a form's localizeInfos.intervals), and the isTimeIntervalAttribute type guard.

Errors

If you want to escape errors inside the sc, leave the "errors" property by default. In this case, you will receive either the entity data or the error object. You need to do a type check. for example, by checking the statusCode property with ".hasOwnProperty"

However, if you want to use the construction "try {} catch(e) {}", set the property "isShell" to the value "false". In this case, you need to handle the error using "try {} catch(e) {}".

Also, you can pass custom functions that will be called inside the sdk with the appropriate error code. These functions receive an error object as an argument. You can process it yourself.

const api = defineOneEntry('your-url', {
    token: 'my-token',
    langCode: 'my-langCode',
    errors: {
        isShell: false,
        customErrors: {
            400: (error) => console.error('Bad Request:', error.message),
            401: (error) => console.error('Unauthorized:', error.message),
            403: (error) => console.error('Forbidden:', error.message),
            404: (error) => console.error('Not Found:', error.message),
            429: (error) => console.error('Rate Limit Exceeded:', error.message),
            500: (error) => console.error('Server Error:', error.message),
            502: (error) => console.error('Bad Gateway:', error.message),
            503: (error) => console.error('Service Unavailable:', error.message),
            504: (error) => console.error('Gateway Timeout:', error.message),
        },
    },
})

Now you can use the following links to jump to specific entries documentation: