@levo-so/client NPM

@levo-so/client

Library to help you build your client-side applications in Node.js, Bun, and Deno using Levo.

@levo-so/client

Installation

You can install @levo-so/client via the terminal.

npm install @levo-so/client

yarn add @levo-so/client

pnpm add @levo-so/client

bun add @levo-so/client

Usage

Initiating the client

You can initialize a new Levo client using the createClient() method.

The Levo client is your entrypoint to the rest of the Levo functionality and is the easiest way to interact with everything we offer within the Levo ecosystem.

import { createClient } from '@levo-so/client';

const client = createClient({
    key: '<api-key>',
    workspace: '<workspace-id>',
    domain: '<domain>', // required if you are using Membership
});

Parameters: ClientOptions

key - Your Levo API key
workspace - Your Levo Workspace ID
domain - The domain of your website that is on, or uses Levo (required if you are using Membership)

Generating the types for the client

@levo-so/client has TypeScript support for type inference, autocompletion, type-safe queries, and more.

With TypeScript, @levo-so/client detects things like required constraints and generated columns. Optional columns are typed as T | null when you select the column. Generated columns will show a type error when you insert to it.

@levo-so/client also detects relationships between collections. A referenced table with one-to-many relationship is typed as T[]. Likewise, a referenced table with many-to-one relationship is typed as T | null.

You can use the Levo CLI to generate the types.

npx @levo-so/client generate-types --workspace <workspace-id> --key <api-key>

bunx @levo-so/client generate-types --workspace <workspace-id> --key <api-key>

Content

Content allows you to manage the content of your workspace.

Creating Entry

Create a new entry in the collection with the specified data.

This method will create a new entry in the collection with the specified data and return the created entry.

const result = await client.content.create('posts', {
    title: 'Hello, World!',
    body: 'This is a test post.',
});

console.log(result.title); // Hello, World!

Find Unique

Get a single document from the collection by its id or unique fields.

This method will return the document with the specified id or null if the document is not found.

const result = await client.content.findUnique('posts', '123');

console.log(result.title); // Hello, World!

Find First

Get the first document from the collection that matches the query.

This method will return the first document that matches the query or null if no document is found.

const result = await client.content.findFirst('posts', {
    where: {
        title: 'Hello, World!',
    },
});

console.log(result.title); // Hello, World!

Find Many

Get all documents from the collection that match the query.

This method will return an array of documents that match the query or an empty array if no documents are found.

const result = await client.content.findMany('posts', {
    where: {
        title: 'Hello, World!',
    },
});

for (const post of result) {
    console.log(post.title); // Hello, World!
}

Edit Entry

Update a document in the collection with the specified data.

This method will update the document with the specified id in the collection with the specified data and return the updated document.

const result = await client.content.edit('posts', '123', {
    title: 'New Title',
    body: 'This is a test post.',
});

console.log(result.title); // New Title

Edit Bulk

Update multiple documents in the collection with the specified data

This method will update multiple documents in the collection with the specified data and return the number of documents that were updated

const where = {
    created_at: {
        gte: new Date(2023, 0, 1),
    }
}

const data = {
    title: 'My Updated Post',
    content: 'This is my updated post'
}

const updated = await client.content.editMany('posts', where, data);

console.log(updated); // 2

Increment

Increment or decrement the values of the fields in the document

The value you provide for the fields will be added/removed to the existing value.

const isIncremented = await client.content.increment('posts', '123', {
    comments: 10,
    likes: -1,
});

console.log(isIncremented); // true

Increment Many

Increment or decrement the values of the fields in many document

The value you provide for the fields will be added/removed to the existing value.

const incrementedCount = await client.content.incrementMany('posts', {
    where: {
        title: 'Hello, World!',
        _status: 'published',
    },
    data: {
        comments: 10,
        likes: -1,
    } 
});

console.log(incrementedCount); // 4

Publish Entry

Publish a document in the collection.

This method will publish the document with the specified id in the collection and return a boolean indicating whether the operation was successful.

const isPublished = await client.content.publish('posts', '123');

console.log(isPublished); // true

Publish Many

Publish multiple documents in the collection.

This method will publish multiple documents in the collection that match the query and return the number of documents that were published.

const publishedCount = await client.content.publishMany('posts', {
    where: {
        title: 'Hello, World!',
    },
});

console.log(publishedCount); // 1

Unpublish Entry

Unpublish a document in the collection.

This method will unpublish the document with the specified id in the collection and return a boolean indicating whether the operation was successful.

const isUnpublished = await client.content.unpublish('posts', '123');

console.log(isUnpublished); // true

Unpublish Many

Unpublish multiple documents in the collection.

This method will unpublish multiple documents in the collection that match the query and return the number of documents that were unpublished.

const unpublishedCount = await client.content.unpublishMany('posts', {
    where: {
        title: 'Hello, World!',
    },
});

console.log(unpublishedCount); // 1

Remove Entry

Remove a document from the collection.

This method will remove the document with the specified id from the collection and return the removed document.

const result = await client.content.remove('posts', '123');

console.log(result.title); // New Title

Remove Many

Remove multiple documents from the collection.

This method will remove multiple documents from the collection that match the query and return the number of documents that were removed.

const removedCount = await client.content.removeMany('posts', {
    title: 'Hello, World!',
});

console.log(removedCount); // 1

Membership

Membership allows you to manage the users of your workspace.

Note: The domain option is required in the createClient for Membership to work. domain is the domain of your website that is on, or uses Levo.

Sign in with Password

This method will sign in a user with their email and password and return the user's account details and a cookie for the domain set in Levo.

const { data: result, cookie } = await client.membership.signInWithPassword({
    email: 'john.doe@example.com',
    password: 'password',
});

response.set('Set-Cookie', cookie);
console.log(result.email); // john.doe@example.com

or use the username instead of the email

const { data: result, cookie } = await client.membership.signInWithPassword({
    username: 'john.doe',
    password: 'password',
});

response.set('Set-Cookie', cookie);
console.log(result.username); // john.doe

Sign up with Password

This method will sign up a user with their email/username, password, and other details and return the user's account details and a cookie for the domain set in Levo.

const result = await client.membership.signupWithPassword({
    email: 'john.doe@example.com',
    password: 'password',
});

console.log(result.email); // john.doe@example.com

Sign Out

Sign out the currently signed in user.

const { data: isSuccess, cookie } = await levo.membership.signOut(token);

// for response to the client to remove the cookie from the browser
response.set('Set-Cookie', cookie); 

console.log(isSuccess); // true

Request Magic Link

This method will send a magic link to the user's email and return a reference to the magic link.

const data = await client.membership.requestMagicLink({
    content: 'john.doe@example.com',
    medium: 'email',
    redirect_uri: 'https://example.com/callback',
});

// Indicates that the request was successful
console.log(data.content); // john.doe@example.com

Note: The domain option is required in the createClient for this to work. domain is the domain of your website that is on, or uses Levo. It should be set-up with Levo's proxy layer, or should be hosted on Levo (which does it automatically).

Request Otp

This method will request a one-time password (OTP) for a user and return if the request was successful.

const result = await client.membership.requestOtp({
    content: 'john.doe@example.com',
    medium: 'email',
});

console.log(result.content); // john.doe@example.com

Sign in with Otp

This method will sign in a user with their one-time password (OTP) and return the user's account details and a cookie for the domain set in Levo.

const { data: result, cookie } = await client.membership.signInWithOtp({
    content: 'john.doe@example.com',
    code: '1234',
});

// for response to the client to set the cookie in the browser
response.set('Set-Cookie', cookie);

console.log(result.email); // john.doe@example.com

Get OAuth URLs

Get the OAuth URLs for the specified redirect URI.

const urls = await client.membership.getOAuthURLs('https://example.com/callback');

console.log(urls.google); 
// https://public-api.levo.so/v1/membership/auth/oauth/callback-from/google?redirect_uri=https://example.com/callback&workspace_id=<workspace_id>

Get Me

Get the account details of the currently signed in user using the access token.

const result = await client.membership.getMe(token);

console.log(result.email); // john.doe@example.com

or directly pass the cookie object

const result = await client.membership.getMe(request.cookies);

console.log(result.email); // john.doe@example.com

Update Me

Update the account details of the currently signed in user using the access token.

const result = await client.membership.updateMe(token, {
    first_name: 'John',
    last_name: 'Doe',
});

console.log(result.first_name); // John

or directly pass the cookie object

const result = await client.membership.updateMe(request.cookies, {
    first_name: 'John',
    last_name: 'Doe',
});

console.log(result.first_name); // John

Change Password

Change the password of the currently signed in user using the access token.

const result = await client.membership.changePassword(token, {
    password: 'new-password',
});

console.log(result.first_name); // John

or directly pass the cookie object

const result = await client.membership.changePassword(request.cookies, {
    password: 'new-password',
});

console.log(result.first_name); // John

Transaction

Transaction allows you to manage the transactions across the Levo API, including content, membership, and more.

With Transaction

Start a transaction and run the provided function within the transaction. If the function throws an error, the transaction will be rolled back. If the function completes successfully, the transaction will be committed.

const result = await client.withTransaction(async (transaction) => {
    const post = await client.content.findUnique('posts', '12345', { transaction });

    const data = {
        title: post.title,
        content: post.content,
        created_at: new Date(),
    }

    const document = await client.content.create('posts', data, { transaction });

    console.log(document._id); // <document_id>
    console.log(document._status); // "draft"

    const isPublished = await client.content.publish('posts', document._id, { transaction });

    console.log(isPublished); // true

    /**
     * The content is accessible only inside of the transaction
     */
    const published = await client.content.get('posts', document._id, { transaction });

    console.log(published._status); // "published"


    /**
     * The content does not exist outside of the transaction
     * and only gets committed when the transaction is executed successfully.
     * 
     * So, if you don't currently pass the transaction the document is not accessible 
     */
    const postOutsideTransaction = await client.content.get('posts', document._id);

    console.log(postOutsideTransaction); // null

    // return whatever you want to return from the transaction
    // as an example, we return the boolean value of whether the transaction was successful
    // this can be any value that you want to return
    return isPublished;
});

console.log(result); // true