@maapi/node

The official Node.js SDK for the Multi-Plant Analytics API (MAAPI).

MAAPI provides enterprise-grade infrastructure for seed-to-sale compliance tracking, facility management, inventory tracking, and agricultural analytics. This SDK allows developers to interact with the MAAPI platform directly from Node.js applications.

Prerequisites

Before installing the SDK, make sure you have:

• Node.js 14.x or later
• An active MAAPI tenant environment
• A valid MAAPI API key
• Your MAAPI Tenant ID

You can create an account and generate your API Key and Tenant ID by signing up at:

https://maapi-bec65.web.app/

Installation

Install the package using npm:

npm install @maapi/node

Authentication and Setup

To use the SDK, you need:

• An API Key used as a Bearer token
• A Tenant ID identifying your MAAPI environment

Keep your API key secure. Do not hard-code it into your application or commit it to source control. Store your credentials in server-side environment variables.

Example .env file:

MAAPI_API_KEY=your_api_key
MAAPI_TENANT_ID=your_tenant_id

Initialize the SDK:

const Maapi = require('@maapi/node');

const maapi = new Maapi(
  process.env.MAAPI_API_KEY,
  process.env.MAAPI_TENANT_ID
);

Core Usage

1. Infrastructure Management

Manage physical operations, facilities, locations, and structural hierarchies.

async function setupFacility() {
  try {
    const facility = await maapi.infrastructure.createFacility({
      name: 'Blue Ridge Cultivation',
      type: 'CULTIVATION'
    });

    console.log(`Facility created with ID: ${facility.id}`);

    return facility;
  } catch (error) {
    console.error('Unable to create facility:', error);
    throw error;
  }
}

2. Inventory Tracking

Manage live plant batches, clones, inventory items, and material lifecycle events.

async function logPlantBatch(facilityId) {
  try {
    const batch = await maapi.inventory.createPlantBatch({
      facilityId,
      count: 500,
      type: 'CLONE'
    });

    console.log(`Plant batch created with ID: ${batch.id}`);

    return batch;
  } catch (error) {
    console.error('Unable to create plant batch:', error);
    throw error;
  }
}

Example usage:

logPlantBatch('your_facility_id');

Advanced Features

Error Handling

The SDK provides dedicated error classes so applications can programmatically handle authentication, validation, and general request failures.

const {
  MaapiAuthenticationError,
  MaapiValidationError
} = require('@maapi/node/lib/MaapiErrors');

async function safeCall() {
  try {
    const facility = await maapi.infrastructure.createFacility({
      name: 'Test Facility',
      type: 'CULTIVATION'
    });

    return facility;
  } catch (error) {
    if (error instanceof MaapiAuthenticationError) {
      console.error('Invalid or expired MAAPI API key.');
    } else if (error instanceof MaapiValidationError) {
      console.error('The request payload failed validation.');
    } else {
      console.error(`MAAPI request failed: ${error.message}`);
    }

    throw error;
  }
}

Local Testing and Custom Gateways

If you are testing your application against a local mock server, emulator, staging environment, or custom gateway, you can override the default production URL during initialization.

const Maapi = require('@maapi/node');

const maapi = new Maapi('test_key', 'test_tenant', {
  baseUrl:
    'http://localhost:5001/YOUR_PROJECT/us-central1/maapiIngress'
});

Do not use test credentials or local gateway URLs in production.

Security Recommendations

• Store API keys in environment variables or a secrets manager.
• Never expose MAAPI credentials in client-side code.
• Never commit .env files to source control.
• Use separate credentials for development, staging, and production.
• Rotate credentials immediately if they are exposed.

Add .env files to your .gitignore:

.env
.env.*
!.env.example

Requirements

| Requirement | Supported Version | | -------------- | ------------------- | | Node.js | 14.x or later | | Module system | CommonJS | | Authentication | API Key + Tenant ID |

Support and Feedback

If you discover a bug, have a feature request, or need assistance using the SDK, contact the MAAPI team at:

[email protected]

License

See the LICENSE file for licensing information.