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

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,
    Events,
    Forms,
    FormData,
    FileUploading,
    GeneralTypes,
    IntegrationCollections,
    Locales,
    Menus,
    Orders,
    Pages,
    Products,
    ProductStatuses,
    System,
    Templates,
    TemplatePreviews,
    Users,
    WS,
} = defineOneEntry('your-url', config)

Or

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".

• '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

1. Log in to your personal account
2. Go to the "Projects" tab and select a project
3. Go to the "Access" tab
4. Set the switch to "Security API Token"
5. Log in to the project, go to the settings section and open the token tab
6. 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,
    },
})

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.

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:

• Documentation

• Admins

• AttributesSets

• AuthProvider

• Blocks

• Events

• FileUploading

• Forms

• FormData

• GeneralTypes

• IntegrationCollections

• Locales

• Menus

• Orders

• Pages

• Payments

• ProductStatuses

• Products

• System

• Templates

• TemplatePreviews

• Users

• WS

• Advanced examples