lumic-backend

Description

The lumic-backend NPM package provides a comprehensive set of executable CRUD (Create, Read, Update, Delete) functions, type and enums definitions, tailored for the Lumic AI platform. Designed for both client-side and server-side applications, it leverages the power of Apollo Client for GraphQL interactions, and TypeGraphQL for building type-safe APIs.

It's primary goal, is to enabled developers to quickly scaffold and interact with their data models, without the need to write elaborate gql operations, or lack certainty of what data to pass through as variables or arguments. Rather, the executable CRUD functions are generated dynamically based on the models defined in the project, and are accessible under the global lumic namespace. Rather than requiring various inputTypes, you simply pass through the data as an object that conforms to the corresponding model's type definition, and the package will handle the rest, irrespective of mutation or query operation being performed.

This package streamlines the development process by offering a unified lumic namespace, encompassing model-specific functions, types, and enums, ensuring consistency and type safety across your application.

Features

This package offers a robust backend solution tailored for the Lumic AI platform, featuring:

• Dynamic Model Functions: Automatically generated CRUD functions for each content model.
• Unified Namespace: Access all functions, types, and enums under the global lumic namespace.
• Type Safety: Comprehensive type definitions ensure consistency and reduce runtime errors.
• GraphQL Integration: Seamless interaction with GraphQL endpoints using Apollo Client.
• Dynamically contructed variables and arguments: No need to worry about constructing gql operations, simply pass through the data as an object that conforms to the model's type definition.
• Server-Side and Client-Side Support: Versatile usage in both environments, including AWS Lambda functions.
• Enums Namespace: Organized enums for consistent value usage across models.
• TypeStrings Namespace: TypeStrings const definitions that are stringified versions of the various model types (including any nested types or enums within them). This is useful when wanting to pass these on to an LLM as a reference (e.g. when asking it to return a specific type of data).
• Automated Documentation: The build script dynamically generates a list of all models and their CRUD resolvers in the README.md.

Prerequisites

To use the lumic-backend package, the only requirement is to ensure you have several environment variables configured (see below). This can be a local development server or a production endpoints for the graphql server, and the corresponding HTTPS and WebSocket URLs.

Environment Variables

Add the folowing to your .env file or add them as environment variables in your deployment environment:

• BACKEND_HTTPS_URL: The HTTPS URL of your GraphQL server. E.g. https://api.lumic.ai/graphql for production, and https://localhost:4000/graphql for local development.

Example .env file:

GRAPHQL_ENDPOINT=http://localhost:4000/graphql
BACKEND_HTTPS_URL=https://api.example.com/graphql
BACKEND_WS_URL=wss://api.example.com/subscriptions

Installation

To install the lumic-backend package, follow these steps:

1. Install NPM Package:

   npm lumic-backend

2. Set Up Environment Variables: Create a .env file in the root of the project and add:

   GRAPHQL_ENDPOINT=http://localhost:4000/graphql // Or any other port you wish to use for the server

Usage

Lumic Namespace

All the dynamically generated functions for each content model are available under the global lumic namespace. You can import and use them in your application as follows:

Client-Side Usage (Root Level)

// client-side/index.ts
import lumic, { types, enums } from 'lumic-backend';

export const main = async () => {
// Example: Create a new User
const userProps = {
  name: 'John Doe',
  email: '[email protected]',
  image: 'https://example.com/johndoe.jpg',
  role: 'ADMIN',
} as types.User;


try {
  const createdUser = await lumic.User.create(userProps) as types.User;
  console.log('Created User:', createdUser);
} catch (error) {
  console.error('Error creating user:', error);
};

// Example: Update a User
const updateUser = async () => {
  const updateProps: types.User = {
    id: 'USER_ID',
    email: '[email protected]',
  };

  try {
    const updatedUser = await lumic.User.update(updateProps) as types.User;
    console.log('Updated User:', updatedUser);
  } catch (error) {
    console.error('Error updating user:', error);
  }
};

// Execute functions
createUser();
updateUser();

};

Server-Side Usage (Within a Lambda Function)

The only difference between client-side and server-side usage is the import statement. On the server-side, you import the functions from lumic-backend/server/index instead of lumic-backend, and you need to provide an Apollo Client instance to the functions with the use of 'fetch' for the HTTP link.

// server-side/lambdaFunction.mjs
import lumic from 'lumic-backend/server/index';

export const handler = async (event) => {
  // Parse the incoming event data
  const data = JSON.parse(event.body);

  // Validate the input
  if (!data.name || !data.type || !data.version || !data.url || !data.website || !data.description) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: 'Missing required fields: name, type, version, url, website, description' }),
    };
  }

  const dependencyObject = {
    name: data.name,
    type: data.type,
    version: data.version,
    url: data.url,
    website: data.website,
    description: data.description,
  };

  try {
    const result = await lumic.dependency.create(dependencyObject);

    return {
      statusCode: 200,
      body: JSON.stringify(result),
    };
  } catch (error) {
    console.error('Error in createOneDependency:', error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: 'An error occurred', details: error.message }),
    };
  }
};

Types Namespace

Types associated with your data models are available under the types namespace. This provides type safety and consistency when working with your models.

// types-example.ts
import { types } from 'lumic-backend';

// Define a new user
const newUser: types.UserCreateInput = {
  username: 'johndoe',
  email: '[email protected]',
  password: 'securepassword',
  role: types.UserRole.ADMIN, // Using enums
};

// Define update input
const updateUser: types.UserUpdateInput = {
  id: 'USER_ID',
  email: '[email protected]',
};

Enums Namespace

Enums associated with your data models are available under the enums namespace. This provides type safety and consistency when working with your models.

// enums-example.ts
import { enums } from 'lumic-backend';

// Assign a user role
const userRole: enums.UserRole = enums.UserRole.MODERATOR;

// Use enums in functions
const setUserRole = (role: enums.UserRole) => {
  // Function logic
};

TypeStrings Namespace

TypeStrings are stringified versions of the various model types (including any nested types or enums within them). These are available under the typeStrings namespace.

Their purpose is to provide a reference to the type of data being requested, which can be passed on to an LLM (Language Learning Model) as a reference within a prompt or query. This is useful when asking the LLM to return a specific type of data that should conform to the model's structure.

// typeStrings-example.ts

import { typeStrings } from 'lumic-backend';

// Use typeStrings in a prompt being sent to an LLM
const prompt = `

... some other prompt text

\${typeStrings.User}

`;

Model CRUD Resolvers

The lumic-backend package includes a comprehensive set of CRUD (Create, Read, Update, Delete) resolvers for each of your models. Each model has the following functions:

• ModelName.create: Create a single record.
• ModelName.createMany: Create multiple records.
• ModelName.update: Update a single record.
• ModelName.delete: Delete a single record.
• ModelName.get: Retrieve a single record by unique identifier.
• ModelName.getAll: Retrieve all records.
• ModelName.findMany: Retrieve multiple records based on criteria.

Model TypeStrings, Types, and available CRUD Resolvers

The lumic-backend package includes a comprehensive set of CRUD (Create, Read, Update, Delete) resolvers for each of your models. Each model has the following functions (available directly under the lumic namespace) and types (under the types namespace):

| Model Name | TypeString | Type | CRUD Resolvers | |------------|------------|------------|-----------------| | Account | typeStrings.Account | types.Account | lumic.account.create, lumic.account.createMany, lumic.account.update, lumic.account.delete, lumic.account.get, lumic.account.getAll, lumic.account.findMany | | Action | typeStrings.Action | types.Action | lumic.action.create, lumic.action.createMany, lumic.action.update, lumic.action.delete, lumic.action.get, lumic.action.getAll, lumic.action.findMany | | ActionEnvironmentVariable | typeStrings.ActionEnvironmentVariable | types.ActionEnvironmentVariable | lumic.actionEnvironmentVariable.create, lumic.actionEnvironmentVariable.createMany, lumic.actionEnvironmentVariable.update, lumic.actionEnvironmentVariable.delete, lumic.actionEnvironmentVariable.get, lumic.actionEnvironmentVariable.getAll, lumic.actionEnvironmentVariable.findMany | | ActionTrigger | typeStrings.ActionTrigger | types.ActionTrigger | lumic.actionTrigger.create, lumic.actionTrigger.createMany, lumic.actionTrigger.update, lumic.actionTrigger.delete, lumic.actionTrigger.get, lumic.actionTrigger.getAll, lumic.actionTrigger.findMany | | Authenticator | typeStrings.Authenticator | types.Authenticator | lumic.authenticator.create, lumic.authenticator.createMany, lumic.authenticator.update, lumic.authenticator.delete, lumic.authenticator.get, lumic.authenticator.getAll, lumic.authenticator.findMany | | City | typeStrings.City | types.City | lumic.city.create, lumic.city.createMany, lumic.city.update, lumic.city.delete, lumic.city.get, lumic.city.getAll, lumic.city.findMany | | Country | typeStrings.Country | types.Country | lumic.country.create, lumic.country.createMany, lumic.country.update, lumic.country.delete, lumic.country.get, lumic.country.getAll, lumic.country.findMany | | Customer | typeStrings.Customer | types.Customer | lumic.customer.create, lumic.customer.createMany, lumic.customer.update, lumic.customer.delete, lumic.customer.get, lumic.customer.getAll, lumic.customer.findMany | | Dependency | typeStrings.Dependency | types.Dependency | lumic.dependency.create, lumic.dependency.createMany, lumic.dependency.update, lumic.dependency.delete, lumic.dependency.get, lumic.dependency.getAll, lumic.dependency.findMany | | Documentation | typeStrings.Documentation | types.Documentation | lumic.documentation.create, lumic.documentation.createMany, lumic.documentation.update, lumic.documentation.delete, lumic.documentation.get, lumic.documentation.getAll, lumic.documentation.findMany | | EnvironmentVariable | typeStrings.EnvironmentVariable | types.EnvironmentVariable | lumic.environmentVariable.create, lumic.environmentVariable.createMany, lumic.environmentVariable.update, lumic.environmentVariable.delete, lumic.environmentVariable.get, lumic.environmentVariable.getAll, lumic.environmentVariable.findMany | | Example | typeStrings.Example | types.Example | lumic.example.create, lumic.example.createMany, lumic.example.update, lumic.example.delete, lumic.example.get, lumic.example.getAll, lumic.example.findMany | | InputObject | typeStrings.InputObject | types.InputObject | lumic.inputObject.create, lumic.inputObject.createMany, lumic.inputObject.update, lumic.inputObject.delete, lumic.inputObject.get, lumic.inputObject.getAll, lumic.inputObject.findMany | | Location | typeStrings.Location | types.Location | lumic.location.create, lumic.location.createMany, lumic.location.update, lumic.location.delete, lumic.location.get, lumic.location.getAll, lumic.location.findMany | | OutputObject | typeStrings.OutputObject | types.OutputObject | lumic.outputObject.create, lumic.outputObject.createMany, lumic.outputObject.update, lumic.outputObject.delete, lumic.outputObject.get, lumic.outputObject.getAll, lumic.outputObject.findMany | | Parameter | typeStrings.Parameter | types.Parameter | lumic.parameter.create, lumic.parameter.createMany, lumic.parameter.update, lumic.parameter.delete, lumic.parameter.get, lumic.parameter.getAll, lumic.parameter.findMany | | Resource | typeStrings.Resource | types.Resource | lumic.resource.create, lumic.resource.createMany, lumic.resource.update, lumic.resource.delete, lumic.resource.get, lumic.resource.getAll, lumic.resource.findMany | | ResourceAction | typeStrings.ResourceAction | types.ResourceAction | lumic.resourceAction.create, lumic.resourceAction.createMany, lumic.resourceAction.update, lumic.resourceAction.delete, lumic.resourceAction.get, lumic.resourceAction.getAll, lumic.resourceAction.findMany | | Schedule | typeStrings.Schedule | types.Schedule | lumic.schedule.create, lumic.schedule.createMany, lumic.schedule.update, lumic.schedule.delete, lumic.schedule.get, lumic.schedule.getAll, lumic.schedule.findMany | | Session | typeStrings.Session | types.Session | lumic.session.create, lumic.session.createMany, lumic.session.update, lumic.session.delete, lumic.session.get, lumic.session.getAll, lumic.session.findMany | | State | typeStrings.State | types.State | lumic.state.create, lumic.state.createMany, lumic.state.update, lumic.state.delete, lumic.state.get, lumic.state.getAll, lumic.state.findMany | | Step | typeStrings.Step | types.Step | lumic.step.create, lumic.step.createMany, lumic.step.update, lumic.step.delete, lumic.step.get, lumic.step.getAll, lumic.step.findMany | | Subsection | typeStrings.Subsection | types.Subsection | lumic.subsection.create, lumic.subsection.createMany, lumic.subsection.update, lumic.subsection.delete, lumic.subsection.get, lumic.subsection.getAll, lumic.subsection.findMany | | Tag | typeStrings.Tag | types.Tag | lumic.tag.create, lumic.tag.createMany, lumic.tag.update, lumic.tag.delete, lumic.tag.get, lumic.tag.getAll, lumic.tag.findMany | | TestData | typeStrings.TestData | types.TestData | lumic.testData.create, lumic.testData.createMany, lumic.testData.update, lumic.testData.delete, lumic.testData.get, lumic.testData.getAll, lumic.testData.findMany | | Trigger | typeStrings.Trigger | types.Trigger | lumic.trigger.create, lumic.trigger.createMany, lumic.trigger.update, lumic.trigger.delete, lumic.trigger.get, lumic.trigger.getAll, lumic.trigger.findMany | | UseCase | typeStrings.UseCase | types.UseCase | lumic.useCase.create, lumic.useCase.createMany, lumic.useCase.update, lumic.useCase.delete, lumic.useCase.get, lumic.useCase.getAll, lumic.useCase.findMany | | User | typeStrings.User | types.User | lumic.user.create, lumic.user.createMany, lumic.user.update, lumic.user.delete, lumic.user.get, lumic.user.getAll, lumic.user.findMany | | VerificationToken | typeStrings.VerificationToken | types.VerificationToken | lumic.verificationToken.create, lumic.verificationToken.createMany, lumic.verificationToken.update, lumic.verificationToken.delete, lumic.verificationToken.get, lumic.verificationToken.getAll, lumic.verificationToken.findMany | | Workflow | typeStrings.Workflow | types.Workflow | lumic.workflow.create, lumic.workflow.createMany, lumic.workflow.update, lumic.workflow.delete, lumic.workflow.get, lumic.workflow.getAll, lumic.workflow.findMany | | WorkflowTrigger | typeStrings.WorkflowTrigger | types.WorkflowTrigger | lumic.workflowTrigger.create, lumic.workflowTrigger.createMany, lumic.workflowTrigger.update, lumic.workflowTrigger.delete, lumic.workflowTrigger.get, lumic.workflowTrigger.getAll, lumic.workflowTrigger.findMany | | Workspace | typeStrings.Workspace | types.Workspace | lumic.workspace.create, lumic.workspace.createMany, lumic.workspace.update, lumic.workspace.delete, lumic.workspace.get, lumic.workspace.getAll, lumic.workspace.findMany | | WorkspaceResource | typeStrings.WorkspaceResource | types.WorkspaceResource | lumic.workspaceResource.create, lumic.workspaceResource.createMany, lumic.workspaceResource.update, lumic.workspaceResource.delete, lumic.workspaceResource.get, lumic.workspaceResource.getAll, lumic.workspaceResource.findMany | | WorkspaceUser | typeStrings.WorkspaceUser | types.WorkspaceUser | lumic.workspaceUser.create, lumic.workspaceUser.createMany, lumic.workspaceUser.update, lumic.workspaceUser.delete, lumic.workspaceUser.get, lumic.workspaceUser.getAll, lumic.workspaceUser.findMany |

Enums

The following enums are available for use under the enums namespace :

| Enum Name | |-----------| | AccountScalarFieldEnum | | ActionEnvironmentVariableScalarFieldEnum | | ActionScalarFieldEnum | | ActionTriggerScalarFieldEnum | | AuthenticatorScalarFieldEnum | | CityScalarFieldEnum | | CountryScalarFieldEnum | | CustomerScalarFieldEnum | | DependencyScalarFieldEnum | | DependencyType | | DocumentationScalarFieldEnum | | EnvironmentVariableScalarFieldEnum | | EventType | | ExampleScalarFieldEnum | | InputObjectScalarFieldEnum | | JsonNullValueFilter | | JsonNullValueInput | | LocationScalarFieldEnum | | NullableJsonNullValueInput | | NullsOrder | | OperationStatus | | OperationType | | OutputObjectScalarFieldEnum | | ParamType | | ParameterScalarFieldEnum | | QueryMode | | ResourceActionScalarFieldEnum | | ResourceScalarFieldEnum | | ResourceStatus | | ResourceType | | ScheduleScalarFieldEnum | | SessionScalarFieldEnum | | SortOrder | | StateScalarFieldEnum | | Status | | StepScalarFieldEnum | | StepType | | SubscriptionPlan | | SubsectionScalarFieldEnum | | TagScalarFieldEnum | | TestDataScalarFieldEnum | | TransactionIsolationLevel | | TriggerScalarFieldEnum | | TriggerType | | UseCaseScalarFieldEnum | | UserRole | | UserScalarFieldEnum | | VerificationTokenScalarFieldEnum | | WorkflowScalarFieldEnum | | WorkflowTriggerScalarFieldEnum | | WorkspaceResourceScalarFieldEnum | | WorkspaceScalarFieldEnum | | WorkspaceUserScalarFieldEnum |