@levo-so/client

v0.0.20-alpha

Published

7 hours ago

Downloads

659

0High
0Medium
0Low

theinternetfolksbot

levo content management cms membership authentication

@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. The domain is the domain of your website that is on, or uses Levo. It is this domain that the membership cookies are set for.

Note: The domain option is required in the createClient or in the options.domain parameter of supported methods for Membership to work.

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, cookies } = await client.membership.signInWithPassword({
    email: '[email protected]',
    password: 'password',
});

for (const cookie of cookies){
    response.append('Set-Cookie', cookie);
}
console.log(result.email); // [email protected]

or use the username instead of the email

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

for (const cookie of cookies){
    response.append('Set-Cookie', cookie);
}
console.log(result.username); // john.doe

You can also optionally pass the domain parameter to override the domain of the client.

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

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: '[email protected]',
    password: 'password',
});

console.log(result.email); // [email protected]

You can also optionally pass the domain parameter to override the domain of the client.

const result = await client.membership.signupWithPassword({
    email: '[email protected]',
    password: 'password'
}, {
    domain: 'example.com'
});

Sign Out

Sign out the currently signed in user.

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

// for response to the client to remove the cookie from the browser
for (const cookie of cookies){
    response.append('Set-Cookie', cookie); 
}

console.log(isSuccess); // true

You can also optionally pass the domain parameter to override the domain of the client.

const { data: isSuccess, cookies } = await levo.membership.signOut(token, {
    domain: 'example.com'
});

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: '[email protected]',
    medium: 'email',
    redirect_uri: 'https://example.com/callback',
});

// Indicates that the request was successful
console.log(data.content); // [email protected]

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: '[email protected]',
    medium: 'email',
});

console.log(result.content); // [email protected]

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, cookies } = await client.membership.signInWithOtp({
    content: '[email protected]',
    code: '1234',
});

// for response to the client to set the cookie in the browser
for (const cookie of cookies){
    response.append('Set-Cookie', cookie);
}

console.log(result.email); // [email protected]

You can also optionally pass the domain parameter to override the domain of the client.

const result = await client.membership.requestMagicLink({
    email: '[email protected]'
}, {
    domain: '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://example.com/.levo/public/api/v1/membership/auth/oauth/callback-from/google?redirect_uri=https://example.com/callback&workspace_id=<workspace_id>

You can also optionally pass the domain parameter to override the domain of the client.

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

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); // [email protected]

or directly pass the cookie object

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

console.log(result.email); // [email protected]

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

Notification

Notification allows you to send various kind of notifications to your users.

Send Notification

Send a custom email, or a richtext which will be sent in Levo's template, to the specified recipients.

Example 1 - Send a custom email with your own HTML

const isSuccess = await client.notification.sendEmail({
    to: ['[email protected]'],
    subject: 'Hello World',
    content: '<p>This is a custom email with HTML</p>',
});

console.log(isSuccess); // true

Example 2 - Send a custom email with your own HTML and customize the email

const isSuccess = await client.notification.sendEmail({
    to: ['[email protected]'],
    subject: 'Hello World',
    content: '<p>This is a custom email with HTML</p>',
    from_name: 'Demo Foundation',
    cc: ['[email protected]'],
    bcc: ['[email protected]'],
    reply_to: '[email protected]'
});

console.log(isSuccess); // true

Example 3 - Send a richtext email with Levo's template

const isSuccess = await client.notification.sendEmail({
    to: ['[email protected]'],
    subject: 'Hello World',
    content: '<p>This will go in a special richtext email template</p>',
    key: 'richtext',
});

console.log(isSuccess); // true

Example 4 - Send a richtext email with Levo's template and customize the email

const isSuccess = await client.notification.sendEmail({
    to: ['[email protected]'],
    subject: 'Hello World',
    content: '<p>This will go in a special richtext email template</p>',
    key: 'richtext',
    from_name: 'Demo Foundation',
    cc: ['[email protected]'],
    bcc: ['[email protected]'],
    reply_to: '[email protected]'
});

console.log(isSuccess); // true

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

License

Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@levo-so/client

Installation

Usage

Initiating the client

Generating the types for the client

Content

Creating Entry

Find Unique

Find First

Find Many

Edit Entry

Edit Bulk

Increment

Increment Many

Publish Entry

Publish Many

Unpublish Entry

Unpublish Many

Remove Entry

Remove Many

Membership

Sign in with Password

Sign up with Password

Sign Out

Request Magic Link

Request Otp

Sign in with Otp

Get OAuth URLs

Get Me

Update Me

Change Password

Notification

Send Notification

Transaction

With Transaction

License