cbamsdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CBAM Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# cbamsdk
+
+Official Node.js SDK for the CBAM Platform API. Integrate EU Carbon Border Adjustment Mechanism (CBAM) reporting, validation, and AI-powered document extraction into your Node.js or TypeScript applications with ease.
+
+## Installation
+
+\`\`\`bash
+npm install cbamsdk
+\`\`\`
+
+## Quick Start
+
+\`\`\`javascript
+const { CBAMClient } = require('cbamsdk');
+
+// Initialize the client
+// Set sandbox: true to use the testing environment
+const client = new CBAMClient('cbam_sk_sandbox_YOUR_KEY', { sandbox: true });
+
+async function run() {
+  try {
+    // 1. Get Default Emission Values
+    const defaults = await client.getDefaultValues();
+    console.log("Default Values:", defaults);
+
+    // 2. Perform AI Intake from a Commercial Invoice
+    const intakeOptions = {
+        payloadFormat: 'json',
+        language: 'en',
+        requestedOutputs: 'official_xml,zip'
+    };
+    
+    // Provide the absolute or relative path to the PDF invoice
+    const result = await client.directIntake('./invoice.pdf', intakeOptions);
+    console.log("Intake Request ID:", result.data.request_id);
+
+    // 3. Download a completed report
+    // const stream = await client.downloadReport('req-sandbox-12345');
+    // stream.pipe(fs.createWriteStream('report.zip'));
+
+  } catch (error) {
+    console.error(error.message);
+  }
+}
+
+run();
+\`\`\`
+
+## Advanced Usage (ERP Integration)
+
+For high-security environments like ERP gateways, use the \`submitIntegration\` method which supports HMAC signatures and custom Idempotency Keys.
+
+\`\`\`javascript
+const result = await client.submitIntegration(
+    './fatura.pdf',
+    { external_reference: 'ERP-INV-001', requested_outputs: ['official_xml'] },
+    { schema_version: 'cbam-intake-v1', target_country: 'DE' }, // optional payload
+    {
+        'X-CBAM-Timestamp': '1778064000',
+        'X-CBAM-Nonce': 'ERP-INV-001-01',
+        'X-CBAM-Signature': 'a1b2c3d4...',
+        'Idempotency-Key': 'ERP-INV-001'
+    }
+);
+\`\`\`
+
+## Features
+- Full API Wrapper for \`/api/v1/cbam/*\`
+- Automatic \`multipart/form-data\` handling for file uploads
+- Clean error handling wrapping HTTP responses
+- Production and Sandbox ready
+
+## License
+MIT

package/index.d.ts

@@ -0,0 +1,104 @@
+export interface CBAMOptions {
+  /**
+   * Set to true to use the Sandbox environment instead of Production.
+   * Default: false
+   */
+  sandbox?: boolean;
+
+  /**
+   * Override the default API base URL.
+   */
+  baseUrl?: string;
+}
+
+export interface IntakeOptions {
+  /**
+   * JSON payload as an object or string.
+   */
+  payload?: any;
+
+  /**
+   * Payload format: 'json' or 'xml'.
+   */
+  payloadFormat?: 'json' | 'xml';
+
+  /**
+   * Target language for the output (e.g., 'en', 'tr', 'de').
+   */
+  language?: string;
+
+  /**
+   * Comma-separated list of requested outputs (e.g., 'official_xml,zip').
+   */
+  requestedOutputs?: string;
+}
+
+export interface SecurityHeaders {
+  'X-CBAM-Signature'?: string;
+  'X-CBAM-Timestamp'?: string;
+  'X-CBAM-Nonce'?: string;
+  'Idempotency-Key'?: string;
+  [key: string]: string | undefined;
+}
+
+export declare class CBAMClient {
+  /**
+   * Initialize the CBAM API Client.
+   * @param apiKey Your CBAM API Secret Key (e.g. cbam_live_sk_...)
+   * @param options Configuration options for the client.
+   */
+  constructor(apiKey: string, options?: CBAMOptions);
+
+  /**
+   * Validate a CBAM payload.
+   * @param payload The CbamTurkIntake JSON payload.
+   */
+  validate(payload: any): Promise<any>;
+
+  /**
+   * Calculate emissions and generate report.
+   * @param payload The calculation request payload.
+   */
+  calculate(payload: any): Promise<any>;
+
+  /**
+   * Get default EU emission values.
+   */
+  getDefaultValues(): Promise<any>;
+
+  /**
+   * Get report generation history.
+   * @param page Page number (default 1).
+   * @param limit Items per page (default 10).
+   */
+  getHistory(page?: number, limit?: number): Promise<any>;
+
+  /**
+   * Download a completed report ZIP package or PDF.
+   * @param reportId The ID of the completed report.
+   * @returns A readable stream of the downloaded file.
+   */
+  downloadReport(reportId: string): Promise<any>;
+
+  /**
+   * Perform direct intake for smart data extraction (Sandbox / Direct API).
+   * @param invoicePath Absolute or relative path to the invoice PDF/XML on disk.
+   * @param options Payload and output configurations.
+   */
+  directIntake(invoicePath: string, options?: IntakeOptions): Promise<any>;
+
+  /**
+   * Advanced Integration Submissions (For ERP / Gateway flows).
+   * Supports HMAC signatures and advanced metadata.
+   * @param invoicePath Absolute or relative path to the invoice file.
+   * @param metadata Metadata object (e.g., external_reference).
+   * @param payload Optional CbamTurkIntake payload (object or string).
+   * @param securityHeaders Headers for security (Signature, Nonce, Timestamp).
+   */
+  submitIntegration(
+    invoicePath: string,
+    metadata?: any,
+    payload?: any,
+    securityHeaders?: SecurityHeaders
+  ): Promise<any>;
+}

package/index.js

@@ -0,0 +1,188 @@
+const axios = require('axios');
+const FormData = require('form-data');
+const fs = require('fs');
+
+class CBAMClient {
+  /**
+   * Initialize the CBAM Node.js SDK
+   * @param {string} apiKey - Your API Secret Key (e.g. cbam_live_sk_...)
+   * @param {Object} options - Configuration options
+   * @param {boolean} options.sandbox - Set to true to use the sandbox environment
+   * @param {string} options.baseUrl - Override the default base URL
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error("API Key is required to initialize CBAMClient.");
+    }
+    
+    const isSandbox = options.sandbox === true;
+    const defaultBaseUrl = isSandbox 
+      ? 'https://sandbox.cbam.com.tr/api/v1' 
+      : 'https://api.cbam.com.tr/api/v1';
+      
+    this.baseUrl = options.baseUrl || defaultBaseUrl;
+    this.apiKey = apiKey;
+
+    this.client = axios.create({
+      baseURL: this.baseUrl,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json'
+      }
+    });
+  }
+
+  async _get(path, params = {}) {
+    try {
+      const response = await this.client.get(path, { params });
+      return response.data;
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+
+  async _post(path, data = {}) {
+    try {
+      const response = await this.client.post(path, data);
+      return response.data;
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+
+  async _postMultipart(path, formData, extraHeaders = {}) {
+    try {
+      const response = await this.client.post(path, formData, {
+        headers: {
+          ...formData.getHeaders(),
+          ...extraHeaders
+        }
+      });
+      return response.data;
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+
+  _handleError(error) {
+    if (error.response) {
+      throw new Error(`CBAM API Error (${error.response.status}): ${JSON.stringify(error.response.data)}`);
+    } else if (error.request) {
+      throw new Error("CBAM API Error: No response received from server.");
+    } else {
+      throw new Error(`CBAM API Error: ${error.message}`);
+    }
+  }
+
+  // -------------------------
+  // CORE ENDPOINTS
+  // -------------------------
+
+  /**
+   * Validate a CBAM payload.
+   * @param {Object} payload - The CbamTurkIntake JSON payload
+   */
+  async validate(payload) {
+    return this._post('/cbam/validate', payload);
+  }
+
+  /**
+   * Calculate emissions and generate report
+   * @param {Object} payload - The calculation request payload
+   */
+  async calculate(payload) {
+    return this._post('/cbam/calculate', payload);
+  }
+
+  /**
+   * Get default EU emission values
+   */
+  async getDefaultValues() {
+    return this._get('/cbam/default-values');
+  }
+
+  /**
+   * Get report generation history
+   * @param {number} page 
+   * @param {number} limit 
+   */
+  async getHistory(page = 1, limit = 10) {
+    return this._get('/cbam/history', { page, limit });
+  }
+
+  /**
+   * Download a completed report ZIP package or PDF
+   * @param {string} reportId 
+   * @returns {Stream} Returns the response stream
+   */
+  async downloadReport(reportId) {
+    try {
+      const response = await this.client.get(`/cbam/download/${reportId}`, {
+        responseType: 'stream'
+      });
+      return response.data;
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+
+  // -------------------------
+  // INTAKE & INTEGRATION
+  // -------------------------
+
+  /**
+   * Perform direct intake for smart data extraction (Sandbox / Direct API)
+   * @param {string} invoicePath - Absolute or relative path to the invoice PDF/XML
+   * @param {Object} options - Payload and output configurations
+   */
+  async directIntake(invoicePath, options = {}) {
+    const form = new FormData();
+    if (invoicePath && fs.existsSync(invoicePath)) {
+      form.append('invoice', fs.createReadStream(invoicePath));
+    } else if (invoicePath) {
+      throw new Error(`Invoice file not found at path: ${invoicePath}`);
+    }
+
+    if (options.payload) {
+       const payloadStr = typeof options.payload === 'object' ? JSON.stringify(options.payload) : options.payload;
+       form.append('payload', payloadStr);
+    }
+    if (options.payloadFormat) form.append('payload_format', options.payloadFormat);
+    if (options.language) form.append('language', options.language);
+    if (options.requestedOutputs) form.append('requested_outputs', options.requestedOutputs);
+
+    return this._postMultipart('/cbam/intake', form);
+  }
+
+  /**
+   * Advanced Integration Submissions (For ERP / Gateway flows)
+   * Supports HMAC signatures and advanced metadata.
+   * @param {string} invoicePath 
+   * @param {Object} metadata 
+   * @param {Object|string} payload 
+   * @param {Object} securityHeaders - X-CBAM-Signature, X-CBAM-Timestamp, etc.
+   */
+  async submitIntegration(invoicePath, metadata = {}, payload = null, securityHeaders = {}) {
+    const form = new FormData();
+    
+    if (invoicePath && fs.existsSync(invoicePath)) {
+      form.append('invoice', fs.createReadStream(invoicePath));
+    } else if (invoicePath) {
+      throw new Error(`Invoice file not found at path: ${invoicePath}`);
+    }
+    
+    if (metadata) {
+      form.append('metadata', typeof metadata === 'object' ? JSON.stringify(metadata) : metadata);
+    }
+    
+    if (payload) {
+       const payloadStr = typeof payload === 'object' ? JSON.stringify(payload) : payload;
+       form.append('payload', payloadStr);
+       form.append('payload_format', 'json');
+    }
+
+    return this._postMultipart('/integrations/cbam/submissions', form, securityHeaders);
+  }
+}
+
+module.exports = { CBAMClient };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cbamsdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for the CBAM Platform API. Integrate EU Carbon Border Adjustment Mechanism (CBAM) reporting, validation, and AI-powered document extraction.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cbam",
+    "carbon",
+    "emissions",
+    "eu",
+    "reporting",
+    "api",
+    "sdk",
+    "sustainability",
+    "invoice",
+    "ocr"
+  ],
+  "author": "CBAM Platform <admin@dynoblastizmir.com.tr>",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.18.1",
+    "form-data": "^4.0.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cbam-platform/cbam-node-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cbam-platform/cbam-node-sdk/issues"
+  },
+  "homepage": "https://cbam.com.tr"
+}