s4kit 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Majer
+
+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,188 @@
+# S4Kit
+
+The simplest way to integrate with SAP S/4HANA.
+
+```typescript
+const customers = await client.Customers.list({ top: 10 });
+```
+
+## Install
+
+```bash
+npm install s4kit
+```
+
+## Quick Start
+
+```typescript
+import { S4Kit } from 's4kit';
+
+const client = S4Kit({ apiKey: 'sk_live_...' });
+
+// List
+const customers = await client.Customers.list({ top: 10 });
+
+// Get
+const customer = await client.Customers.get('ALFKI');
+
+// Create
+const created = await client.Customers.create({
+  CustomerID: 'NEWCO',
+  CompanyName: 'New Company'
+});
+
+// Update
+await client.Customers.update('NEWCO', { CompanyName: 'Updated Name' });
+
+// Delete
+await client.Customers.delete('NEWCO');
+```
+
+## Type Safety
+
+Generate types for full autocomplete and type checking:
+
+```bash
+npx s4kit generate-types --api-key sk_live_... --output ./types
+
+# Self-hosted
+npx s4kit generate-types --api-key sk_live_... --base-url http://localhost:3002 --output ./types
+```
+
+```typescript
+import { S4Kit } from 's4kit';
+import './types';  // Enable type inference
+
+const client = S4Kit({ apiKey: 'sk_live_...' });
+
+// Full autocomplete on entity names
+const customers = await client.Customers.list({
+  select: ['CustomerID', 'CompanyName', 'City'],  // Type-safe fields
+  filter: { City: 'Berlin' },
+  top: 10
+});
+
+// customers is Customer[], not any[]
+customers.forEach(c => {
+  console.log(c.CompanyName);  // Autocomplete works!
+});
+```
+
+## Query Options
+
+```typescript
+await client.Products.list({
+  // Select fields
+  select: ['ProductID', 'ProductName', 'UnitPrice'],
+
+  // Filter - multiple formats
+  filter: { Category: 'Beverages' },                    // Simple equality
+  filter: { UnitPrice: { gt: 20 } },                    // Operators: gt, lt, ge, le, ne
+  filter: { ProductName: { contains: 'Ch' } },          // String: contains, startswith, endswith
+  filter: "UnitPrice gt 20 and Category eq 'Beverages'", // Raw OData
+
+  // Pagination
+  top: 10,
+  skip: 20,
+
+  // Sorting
+  orderBy: { UnitPrice: 'desc' },
+  orderBy: [{ Category: 'asc' }, { ProductName: 'asc' }],
+
+  // Expand relations
+  expand: ['Category', 'Supplier'],
+  expand: {
+    Category: true,
+    Supplier: { select: ['CompanyName'] }
+  }
+});
+```
+
+## Count & Pagination
+
+```typescript
+// Get count
+const total = await client.Products.count();
+const filtered = await client.Products.count({ filter: { Discontinued: false } });
+
+// List with count
+const { value, count } = await client.Products.listWithCount({ top: 10 });
+console.log(`Showing ${value.length} of ${count}`);
+
+// Iterate all pages
+for await (const page of client.Products.paginate({ pageSize: 100 })) {
+  console.log(`Processing ${page.value.length} items`);
+}
+
+// Get all (auto-pagination)
+const all = await client.Products.all();
+```
+
+## Navigation Properties
+
+```typescript
+// Access related entities
+const orderItems = await client.Orders.nav(10248, 'Order_Details').list();
+```
+
+## Batch Operations
+
+```typescript
+// Multiple operations in one request
+const results = await client.batch([
+  { method: 'GET', entity: 'Products', id: 1 },
+  { method: 'POST', entity: 'Products', data: { ProductName: 'New' } },
+  { method: 'PATCH', entity: 'Products', id: 2, data: { UnitPrice: 29.99 } },
+  { method: 'DELETE', entity: 'Products', id: 3 },
+]);
+
+// Atomic transaction (all succeed or all fail)
+await client.changeset({
+  operations: [
+    { method: 'POST', entity: 'Orders', data: orderData },
+    { method: 'POST', entity: 'Order_Details', data: item1 },
+    { method: 'POST', entity: 'Order_Details', data: item2 },
+  ]
+});
+```
+
+## Error Handling
+
+```typescript
+import { S4KitError, NotFoundError, ValidationError } from 's4kit';
+
+try {
+  await client.Products.get(99999);
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Product not found');
+  } else if (error instanceof ValidationError) {
+    console.log('Invalid data:', error.details);
+  } else if (error instanceof S4KitError) {
+    console.log(error.friendlyMessage);
+    console.log(error.help);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = S4Kit({
+  apiKey: 'sk_live_...',                           // Required
+  baseUrl: 'https://api.s4kit.com/api/proxy',      // Default (or self-hosted)
+  connection: 'prod',                              // Default SAP instance
+  timeout: 30000,                                  // Request timeout (ms)
+  retries: 3,                                      // Retry on failure
+});
+
+// Override per request
+await client.Products.list({
+  connection: 'sandbox',  // Use different instance
+  service: 'API_PRODUCT'  // Specify service
+});
+```
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var VERSION = "0.1.0";
+function parseArgs(args) {
+  const options = {};
+  const positional = [];
+  let command = "help";
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "generate-types" || arg === "init" || arg === "help" || arg === "version") {
+      command = arg;
+    } else if (arg === "--api-key" || arg === "-k") {
+      options.apiKey = args[++i] ?? "";
+    } else if (arg === "--base-url" || arg === "-u") {
+      options.baseUrl = args[++i] ?? "";
+    } else if (arg === "--connection" || arg === "-c") {
+      options.connection = args[++i] ?? "";
+    } else if (arg === "--output" || arg === "-o") {
+      options.output = args[++i] ?? "";
+    } else if (arg === "--help" || arg === "-h") {
+      command = "help";
+    } else if (arg === "--version" || arg === "-v") {
+      command = "version";
+    } else if (!arg.startsWith("-")) {
+      positional.push(arg);
+    }
+  }
+  return { command, options, positional };
+}
+function showHelp() {
+  console.log(`
+s4kit - The lightweight, type-safe SDK for SAP S/4HANA
+
+Usage:
+  s4kit <command> [options]
+
+Commands:
+  generate-types    Generate TypeScript types from SAP metadata
+  init              Initialize S4Kit in your project
+  help              Show this help message
+  version           Show version number
+
+Options:
+  -k, --api-key     API key for S4Kit platform
+  -u, --base-url    Proxy URL (default: https://api.s4kit.com/api/proxy)
+  -c, --connection  SAP connection alias
+  -o, --output      Output directory for generated files
+
+Examples:
+  # Generate types for all entities accessible by your API key
+  s4kit generate-types --api-key sk_live_xxx --output ./types
+
+  # Generate types for a specific connection
+  s4kit generate-types -k sk_live_xxx -c erp-prod -o ./types
+
+  # Initialize S4Kit in your project
+  s4kit init
+
+Environment Variables:
+  S4KIT_API_KEY     Default API key (can be overridden with --api-key)
+  S4KIT_BASE_URL    Default base URL
+
+Documentation: https://github.com/michal-majer/s4kit
+`);
+}
+function showVersion() {
+  console.log(`s4kit v${VERSION}`);
+}
+async function generateTypes(options) {
+  const apiKey = options.apiKey || process.env.S4KIT_API_KEY;
+  const baseUrl = options.baseUrl || process.env.S4KIT_BASE_URL || "https://api.s4kit.com/api/proxy";
+  const output = options.output || "./s4kit-types";
+  if (!apiKey) {
+    console.error("Error: API key is required");
+    console.error("  Use --api-key or set S4KIT_API_KEY environment variable");
+    process.exit(1);
+  }
+  console.log("Generating TypeScript types...");
+  console.log(`  API: ${baseUrl}`);
+  console.log(`  Output: ${output}`);
+  try {
+    const response = await fetch(`${baseUrl}/$types`, {
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Accept": "application/typescript"
+      }
+    });
+    if (!response.ok) {
+      if (response.status === 401) {
+        console.error("Error: Invalid API key");
+        process.exit(1);
+      }
+      if (response.status === 404) {
+        console.error("Error: Types endpoint not found. Make sure you have the correct base URL.");
+        process.exit(1);
+      }
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const types = await response.text();
+    const fs = await import("fs");
+    const path = await import("path");
+    const outputDir = path.resolve(output);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const typesFile = path.join(outputDir, "index.d.ts");
+    fs.writeFileSync(typesFile, types);
+    console.log(`
+Types generated successfully!`);
+    console.log(`  ${typesFile}`);
+    console.log(`
+Usage:`);
+    console.log(`  import type { A_BusinessPartner } from '${output}';`);
+  } catch (error) {
+    console.error("Failed to generate types:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+async function init() {
+  console.log("Initializing S4Kit...\n");
+  const fs = await import("fs");
+  const configFile = "s4kit.config.ts";
+  if (fs.existsSync(configFile)) {
+    console.log(`Config file already exists: ${configFile}`);
+    return;
+  }
+  const config = `// S4Kit Configuration
+// See: https://github.com/michal-majer/s4kit
+
+export default {
+  // Your S4Kit API key (use environment variable in production)
+  apiKey: process.env.S4KIT_API_KEY || '',
+
+  // Default SAP connection alias
+  connection: 'erp-dev',
+
+  // Optional: Base URL (default: https://api.s4kit.com)
+  // baseUrl: 'https://api.s4kit.com',
+};
+`;
+  fs.writeFileSync(configFile, config);
+  console.log(`Created ${configFile}`);
+  const typesDir = "./s4kit-types";
+  if (!fs.existsSync(typesDir)) {
+    fs.mkdirSync(typesDir, { recursive: true });
+    console.log(`Created ${typesDir}/`);
+  }
+  const gitignore = ".gitignore";
+  if (fs.existsSync(gitignore)) {
+    const content = fs.readFileSync(gitignore, "utf-8");
+    if (!content.includes("s4kit-types")) {
+      fs.appendFileSync(gitignore, "\n# S4Kit generated types\ns4kit-types/\n");
+      console.log(`Updated ${gitignore}`);
+    }
+  }
+  console.log(`
+Next steps:
+  1. Set your API key in S4KIT_API_KEY environment variable
+  2. Run: npx s4kit generate-types
+  3. Import types in your code:
+     import { S4Kit } from 's4kit';
+     import type { A_BusinessPartner } from './s4kit-types';
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const { command, options } = parseArgs(args);
+  switch (command) {
+    case "generate-types":
+      await generateTypes(options);
+      break;
+    case "init":
+      await init();
+      break;
+    case "version":
+      showVersion();
+      break;
+    case "help":
+    default:
+      showHelp();
+      break;
+  }
+}
+main().catch((error) => {
+  console.error("Unexpected error:", error);
+  process.exit(1);
+});

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var VERSION = "0.1.0";
+function parseArgs(args) {
+  const options = {};
+  const positional = [];
+  let command = "help";
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "generate-types" || arg === "init" || arg === "help" || arg === "version") {
+      command = arg;
+    } else if (arg === "--api-key" || arg === "-k") {
+      options.apiKey = args[++i] ?? "";
+    } else if (arg === "--base-url" || arg === "-u") {
+      options.baseUrl = args[++i] ?? "";
+    } else if (arg === "--connection" || arg === "-c") {
+      options.connection = args[++i] ?? "";
+    } else if (arg === "--output" || arg === "-o") {
+      options.output = args[++i] ?? "";
+    } else if (arg === "--help" || arg === "-h") {
+      command = "help";
+    } else if (arg === "--version" || arg === "-v") {
+      command = "version";
+    } else if (!arg.startsWith("-")) {
+      positional.push(arg);
+    }
+  }
+  return { command, options, positional };
+}
+function showHelp() {
+  console.log(`
+s4kit - The lightweight, type-safe SDK for SAP S/4HANA
+
+Usage:
+  s4kit <command> [options]
+
+Commands:
+  generate-types    Generate TypeScript types from SAP metadata
+  init              Initialize S4Kit in your project
+  help              Show this help message
+  version           Show version number
+
+Options:
+  -k, --api-key     API key for S4Kit platform
+  -u, --base-url    Proxy URL (default: https://api.s4kit.com/api/proxy)
+  -c, --connection  SAP connection alias
+  -o, --output      Output directory for generated files
+
+Examples:
+  # Generate types for all entities accessible by your API key
+  s4kit generate-types --api-key sk_live_xxx --output ./types
+
+  # Generate types for a specific connection
+  s4kit generate-types -k sk_live_xxx -c erp-prod -o ./types
+
+  # Initialize S4Kit in your project
+  s4kit init
+
+Environment Variables:
+  S4KIT_API_KEY     Default API key (can be overridden with --api-key)
+  S4KIT_BASE_URL    Default base URL
+
+Documentation: https://github.com/michal-majer/s4kit
+`);
+}
+function showVersion() {
+  console.log(`s4kit v${VERSION}`);
+}
+async function generateTypes(options) {
+  const apiKey = options.apiKey || process.env.S4KIT_API_KEY;
+  const baseUrl = options.baseUrl || process.env.S4KIT_BASE_URL || "https://api.s4kit.com/api/proxy";
+  const output = options.output || "./s4kit-types";
+  if (!apiKey) {
+    console.error("Error: API key is required");
+    console.error("  Use --api-key or set S4KIT_API_KEY environment variable");
+    process.exit(1);
+  }
+  console.log("Generating TypeScript types...");
+  console.log(`  API: ${baseUrl}`);
+  console.log(`  Output: ${output}`);
+  try {
+    const response = await fetch(`${baseUrl}/$types`, {
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Accept": "application/typescript"
+      }
+    });
+    if (!response.ok) {
+      if (response.status === 401) {
+        console.error("Error: Invalid API key");
+        process.exit(1);
+      }
+      if (response.status === 404) {
+        console.error("Error: Types endpoint not found. Make sure you have the correct base URL.");
+        process.exit(1);
+      }
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const types = await response.text();
+    const fs = await import("fs");
+    const path = await import("path");
+    const outputDir = path.resolve(output);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const typesFile = path.join(outputDir, "index.d.ts");
+    fs.writeFileSync(typesFile, types);
+    console.log(`
+Types generated successfully!`);
+    console.log(`  ${typesFile}`);
+    console.log(`
+Usage:`);
+    console.log(`  import type { A_BusinessPartner } from '${output}';`);
+  } catch (error) {
+    console.error("Failed to generate types:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+async function init() {
+  console.log("Initializing S4Kit...\n");
+  const fs = await import("fs");
+  const configFile = "s4kit.config.ts";
+  if (fs.existsSync(configFile)) {
+    console.log(`Config file already exists: ${configFile}`);
+    return;
+  }
+  const config = `// S4Kit Configuration
+// See: https://github.com/michal-majer/s4kit
+
+export default {
+  // Your S4Kit API key (use environment variable in production)
+  apiKey: process.env.S4KIT_API_KEY || '',
+
+  // Default SAP connection alias
+  connection: 'erp-dev',
+
+  // Optional: Base URL (default: https://api.s4kit.com)
+  // baseUrl: 'https://api.s4kit.com',
+};
+`;
+  fs.writeFileSync(configFile, config);
+  console.log(`Created ${configFile}`);
+  const typesDir = "./s4kit-types";
+  if (!fs.existsSync(typesDir)) {
+    fs.mkdirSync(typesDir, { recursive: true });
+    console.log(`Created ${typesDir}/`);
+  }
+  const gitignore = ".gitignore";
+  if (fs.existsSync(gitignore)) {
+    const content = fs.readFileSync(gitignore, "utf-8");
+    if (!content.includes("s4kit-types")) {
+      fs.appendFileSync(gitignore, "\n# S4Kit generated types\ns4kit-types/\n");
+      console.log(`Updated ${gitignore}`);
+    }
+  }
+  console.log(`
+Next steps:
+  1. Set your API key in S4KIT_API_KEY environment variable
+  2. Run: npx s4kit generate-types
+  3. Import types in your code:
+     import { S4Kit } from 's4kit';
+     import type { A_BusinessPartner } from './s4kit-types';
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const { command, options } = parseArgs(args);
+  switch (command) {
+    case "generate-types":
+      await generateTypes(options);
+      break;
+    case "init":
+      await init();
+      break;
+    case "version":
+      showVersion();
+      break;
+    case "help":
+    default:
+      showHelp();
+      break;
+  }
+}
+main().catch((error) => {
+  console.error("Unexpected error:", error);
+  process.exit(1);
+});