Welcome to the documentation for the Kanvas SDK, a TypeScript SDK designed exclusively to seamlessly connect with the Kanvas Niche ecosystem. This SDK is crafted to enhance the development of headless applications by providing easy-to-use interfaces for interacting with various modules within the Kanvas Niche ecosystem.
- Introduction
- Installation
- Configuration
- Core Modules
- Tips and Best Practices
- Troubleshooting
- Contributing
- Support
Kanvas Core JS is a powerful TypeScript SDK for seamless integration with the Kanvas Niche ecosystem. It provides a comprehensive set of modules for building robust applications.
npm install @kanvas/coreInitialize the SDK:
import KanvasCore, { genericAuthMiddleware } from '@kanvas/core';
const getAuthToken = async () => localStorage.getItem("token") || null;
const kanvas = new KanvasCore({
url: 'YOUR_KANVAS_URL',
key: 'YOUR_KANVAS_API_KEY',
middlewares: [genericAuthMiddleware(getAuthToken)],
adminKey: 'OPTIONAL_ADMIN_KEY',
});Manage application-level operations.
// Create a new app
const newApp = await kanvas.app.createApp({
name: 'MyApp',
url: 'https://myapp.com',
description: 'App description',
domain: 'myapp.com',
is_actived: true,
ecosystem_auth: true,
payments_active: false,
is_public: true,
domain_based: false
});
// Get apps with access
const apps = await kanvas.app.getAppsWithAccess();Handle authentication and sessions.
// Login
const session = await kanvas.auth.login('user@example.com', 'password');
// Logout
await kanvas.auth.logout();
// Refresh token
const newToken = await kanvas.auth.refreshToken('current_refresh_token');Manage user accounts and profiles.
// Register new user
const newUser = await kanvas.users.register({
email: 'newuser@example.com',
password: 'securePassword',
firstname: 'John',
lastname: 'Doe'
});
// Get current user data
const userData = await kanvas.users.getUserData();
// Update user profile
const updatedUser = await kanvas.users.updateUserData(userId, {
firstname: 'Jane',
lastname: 'Doe',
displayname: 'JaneDoe'
});Manage custom fields for entities.
// Set a custom field
await kanvas.customFields.setCustomField({
name: 'customField',
data: 'fieldValue',
system_module_uuid: 'moduleUUID',
entity_id: 'entityId'
});
// Get a custom field
const customField = await kanvas.customFields.getCustomField({
name: 'customField',
system_module_uuid: 'moduleUUID',
entity_id: 'entityId'
});Manage geographical data.
// Get all countries
const countries = await kanvas.locations.getAllCountries();
// Get states for a country
const states = await kanvas.locations.getStatesByCountry(countryId);Manage company data.
// Create a company
const newCompany = await kanvas.companies.createCompany({
name: 'New Company',
website: 'https://newcompany.com',
address: '123 Company St',
zipcode: '12345',
email: 'info@newcompany.com'
});
// Get companies
const companies = await kanvas.companies.getCompanies({
first: 10,
page: 1,
where: { column: 'IS_ACTIVE', operator: 'EQ', value: true }
});Manage company branches.
// Create a branch
const newBranch = await kanvas.companiesBranches.createCompanyBranch({
name: 'New Branch',
companies_id: 'companyId',
address: '456 Branch Ave',
is_default: false
});
// Get branches
const branches = await kanvas.companiesBranches.getCompanyBranches({
first: 10,
page: 1,
where: { column: 'COMPANIES_ID', operator: 'EQ', value: 'companyId' }
});Manage sales leads.
// Create a lead
const newLead = await kanvas.leads.createLead({
title: 'New Lead',
branch_id: 1,
pipeline_stage_id: 1,
people: { firstname: 'John', lastname: 'Doe' },
organization: { name: 'Lead Org' },
custom_fields: [{ name: 'Source', data: 'Website' }]
});
// Get leads
const leads = await kanvas.leads.getAllLeads(10, 1);Manage product inventory.
// Create a product
const newProduct = await kanvas.inventory.createProduct({
name: 'New Product',
description: 'Product description',
products_types_id: 1,
is_published: true
});
// Get products
const products = await kanvas.inventory.getProduct({
first: 10,
page: 1,
whereCondition: { column: 'IS_PUBLISHED', operator: 'EQ', value: true }
});Manage sales agents.
// Get all agents
const agents = await kanvas.agents.getAllAgents(10, 1);
// Get agents by user ID
const userAgents = await kanvas.agents.getAgentsByUserID('userId');Handle e-commerce operations.
// Add to cart
await kanvas.cart.addToCart({
input: [{ quantity: 2, variant_id: 'variantId' }]
});
// Create an order
const order = await kanvas.order.createOrder({
input: {
cartId: 'default',
payment: {
name: 'John Doe',
number: '4111111111111111',
exp_month: 12,
exp_year: 2025,
cvv: 123
}
}
});Manage user-created lists.
// Create a list
const newList = await kanvas.usersLists.createUserList({
name: 'My List',
description: 'List description',
is_public: true,
is_default: false
});
// Get lists
const lists = await kanvas.usersLists.getUsersLists(
{ column: 'USER_ID', operator: 'EQ', value: 'userId' },
1,
10
);Handle messaging functionality.
// Create a message
const newMessage = await kanvas.messages.createMessage({
message_verb: 'POST',
message: 'Hello, world!',
system_modules_id: 'moduleId',
entity_id: 'entityId'
});
// Get messages
const messages = await kanvas.messages.getMessages(
{ column: 'ENTITY_ID', operator: 'EQ', value: 'entityId' },
{ column: 'SYSTEM_MODULES_ID', operator: 'EQ', value: 'moduleId' },
[{ column: 'CREATED_AT', order: 'DESC' }],
'search term',
10,
1
);Manage user roles and permissions.
// Get roles
const roles = await kanvas.roles.getRoles();
// Assign role to user
await kanvas.roles.assignRoleUser({ userId: 'userId', role: 'roleId' });
// Create a role
const newRole = await kanvas.roles.createRole({ name: 'New Role' });Handle file operations.
// Upload a file
const uploadedFile = await kanvas.filesystem.uploadFile(fileData);
// Get entity files
const files = await kanvas.filesystem.getEntityFiles({
name: 'entity_name',
data: 'entity_data',
system_module_uuid: 'moduleUUID',
entity_id: 'entityId'
});Manage discussion topics.
// Create a topic
const newTopic = await kanvas.topics.createTopic({
name: 'New Topic',
slug: 'new-topic',
weight: 1,
is_feature: 1,
status: true
});
// Get topics
const topics = await kanvas.topics.getTopics({
column: 'STATUS',
operator: 'EQ',
value: true
});Manage system modules.
// Get modules
const modules = await kanvas.systemModules.getSystemModules(10, 1);
// Get module by slug
const module = await kanvas.systemModules.getSystemModulesBySlug('module-slug');Manage follow relationships.
// Follow a user
await kanvas.follow.followUser(userId);
// Get followers
const followers = await kanvas.follow.getFollowers(userId);Manage people records.
// Create a person
const newPerson = await kanvas.people.createPeople({
firstname: 'John',
lastname: 'Doe',
contacts: [{ value: 'john@example.com', contacts_types_id: 1 }]
});
// Get people
const people = await kanvas.people.getPeople({
first: 10,
page: 1,
where: { column: 'LASTNAME', operator: 'EQ', value: 'Doe' }
});Handle system notifications.
// Get notifications
const notifications = await kanvas.notifications.getNotifications(
{ column: 'IS_READ', operator: 'EQ', value: false },
{ nested_key: 'entity.id', value: 'entityId' },
{ verb: 'created', event: 'new_message' },
10,
1
);
// Send notification
await kanvas.notifications.sendNotificationBaseTemplate(
'welcome_template',
{ user_name: 'John' },
['email'],
[userId]
);Manage communication channels.
// Create a channel
const newChannel = await kanvas.channels.createChannel({
name: 'New Channel',
slug: 'new-channel',
description: 'Channel description',
entity_namespace_uuid: 'namespaceUUID',
entity_id: 'entityId'
});
// Get channels
const channels = await kanvas.channels.getChannels(
{ column: 'ENTITY_ID', operator: 'EQ', value: 'entityId' },
10,
1
);Manage organization-related operations.
// Update organization
const updatedOrg = await kanvas.organization.updateOrganization({
id: 'orgId',
input: {
name: 'Updated Org Name',
address: 'New Address'
}
});Manage tagging functionality.
// Create a tag
const newTag = await kanvas.tags.createTag({
name: 'New Tag',
slug: 'new-tag',
weight: 1
});
// Get tags
const tags = await kanvas.tags.getTags({
where: { column: 'IS_ACTIVE', operator: 'EQ', value: true }
});Manage application, company, and user settings.
// Fetch app settings
const appSettings = await kanvas.settings.fetchAppSettings();
// Get specific app settings
const specificAppSettings = await kanvas.settings.getAppSettings();
// Get company settings
const companySettings = await kanvas.settings.getCompanySettings('company_uuid');
// Get user settings
const userSettings = await kanvas.settings.getUserSettings('user_uuid');
// Set user settings
await kanvas.settings.setUserSettings({
key: 'theme',
value: 'dark',
entity_uuid: 'user_uuid'
});
// Set app settings
await kanvas.settings.setAppSettings({
key: 'maintenance_mode',
value: false,
entity_uuid: 'app_uuid'
});
// Set company settings
await kanvas.settings.setCompanySettings({
key: 'logo_url',
value: 'https://example.com/logo.png',
entity_uuid: 'company_uuid'
});
// Delete company settings
await kanvas.settings.deleteCompanySettings({
key: 'old_setting',
entity_uuid: 'company_uuid'
});
// Delete user settings
await kanvas.settings.deleteUserSettings({
key: 'deprecated_preference',
entity_uuid: 'user_uuid'
});Submit receiver data to the Kanvas API.
// Submit receiver data
const uuid = '01f6ca9f-fdba-41a1-8e05-bf1fd56122fc';
const receiverData = {
title: "jhon doe store",
pipeline_stage_id: 0,
people: {
firstname: "jhon",
lastname: "doe",
contacts: [
{ value: "example@store.com", contacts_types_id: 1, weight: 0 },
{ value: "8738999933", contacts_types_id: 2, weight: 100 },
{ value: "8738999911", contacts_types_id: 2, weight: 50 }
],
address: [
{ address: "Sony Store", city: "New York" }
],
custom_fields: [
{ name: "title", data: "CEO" }
]
},
organization: {
name: "jhon doe"
},
custom_fields: [
{ name: "organization_phone", data: "8093520515151" },
{ name: "organization_fax", data: "38329348234982" },
{ name: "organization_email", data: "nose@nose.com" },
{ name: "organization_website", data: "https://nose.com" },
{ name: "organization_online_store", data: "https://nose2.com" },
{ name: "organization_address", data: { city: "New York", state: "NY", zip: 383838, country: "US" } },
{ name: "organization_social_url", data: "https://nose3.com" },
{ name: "organization_remittance_address", data: { city: "New York", state: "NY", zip: 383838, country: "US" } },
{ name: "organization_state_of_imporcopration", data: "FL" },
{ name: "organization_tax_ein", data: "2342342" },
{ name: "organization_number_of_stores", data: 2 },
{ name: "organization_volumn_of_sales", data: 23333 }
],
files: [
{ name: "something", url: "https://cdn.memod.com/images/lT5sJMf.jpg" }
]
};
try {
const result = await kanvas.receiver.submitReceiverData(uuid, receiverData);
console.log('Receiver data submitted successfully:', result);
} catch (error) {
console.error('Error submitting receiver data:', error);
}Tips for using the Settings module:
- Use settings to store configuration that might change without requiring code updates.
- Ensure you have the necessary permissions when accessing or modifying settings.
- Company and user settings can be used to customize the application experience for different entities.
- App settings are global and should be used for application-wide configurations.
Error handling example:
try {
const appSettings = await kanvas.settings.getAppSettings();
// Use app settings
} catch (error) {
console.error('Failed to fetch app settings:', error);
// Handle the error appropriately
}- Always handle errors using try-catch blocks.
- Use pagination for large data sets to improve performance.
- Implement proper authentication and keep tokens secure.
- Utilize custom fields for extending entity properties.
- Regularly refresh authentication tokens to maintain security.
- Use appropriate data filtering and sorting in queries.
- Implement proper access control using roles and permissions.
- Authentication Issues: Ensure your API key and tokens are correct and not expired.
- Rate Limiting: Implement proper request throttling to avoid hitting rate limits.
- Data Inconsistencies: Always validate input data before sending requests.
- Performance Issues: Use pagination and limit the amount of data requested when possible.
Remember to replace placeholder values (like 'YOUR_KANVAS_URL') with actual values. This README provides a comprehensive overview of the Kanvas Core JS SDK, its modules, and how to use them. Always refer to the latest API documentation for the most up-to-date information on available methods and their parameters.
For a comprehensive list of available methods and their descriptions, refer to the API Reference.
If you'd like to contribute to the Kanvas Niche SDK, please follow our Contribution Guidelines. TBD
If you have any questions, feedback, or issues, feel free to reach out to our team at the TBD
Happy coding with Kanvas!