s4kit 0.1.9 → 0.1.11

package/README.md

@@ -64,28 +64,78 @@ The platform handles CSRF tokens, authentication, and connection pooling — you
 
 ---
 
-## Type Generation
+## Type Generation (Recommended)
 
-Generate TypeScript types from your SAP system for full autocomplete and type safety:
+> **This is the key feature of S4Kit.** Generate TypeScript types directly from your SAP system's OData metadata for full autocomplete and compile-time type safety.
+
+### Why Generate Types?
+
+Without types, the SDK works but you lose the main benefit - type safety:
+```typescript
+// Without types - works but no autocomplete, no type checking
+const partners = await client.A_BusinessPartner.list(); // partners is any[]
+```
+
+With generated types:
+```typescript
+// With types - full IDE support and compile-time validation
+const partners = await client.A_BusinessPartner.list({
+  select: ['BusinessPartner', 'BusinessPartnerName'],  // ← Autocomplete!
+});
+partners.forEach(p => console.log(p.BusinessPartnerName));  // ← Type-safe!
+```
+
+### Generating Types
 
 ```bash
-npx s4kit generate-types --api-key sk_live_... --base-url https://staging.proxy.s4kit.com/api/proxy --output ./types
+# Basic usage
+npx s4kit generate-types --api-key sk_live_... --output ./types
+
+# With all options
+npx s4kit generate-types \
+  --api-key sk_live_...                                    # Required
+  --output ./types                                         # Output directory (default: ./s4kit-types)
+  --base-url https://staging.proxy.s4kit.com/api/proxy    # Custom proxy URL
+  --connection my-sap-system                               # Specific connection only
 ```
 
+### Using Generated Types
+
 ```typescript
 import { S4Kit } from 's4kit';
-import './types';  // Enable type inference
+import './types';  // ← This enables type inference
 
 const client = S4Kit({ apiKey: 'sk_live_...' });
 
 // Full autocomplete on entity names and fields
 const partners = await client.A_BusinessPartner.list({
-  select: ['BusinessPartner', 'BusinessPartnerName'],  // ← Type-safe!
+  select: ['BusinessPartner', 'BusinessPartnerName'],
   filter: { BusinessPartnerCategory: '1' }
 });
 
 // partners is A_BusinessPartner[], not any[]
-partners.forEach(p => console.log(p.BusinessPartnerName));  // ← Autocomplete works!
+partners.forEach(p => console.log(p.BusinessPartnerName));
+```
+
+### What You Get
+
+- **Entity autocomplete** - `client.` shows all available entities
+- **Field autocomplete** - `select`, `filter`, `orderBy` show valid fields
+- **Type-safe filters** - operators match field types (string fields get `contains`, number fields get `gt`/`lt`)
+- **Proper return types** - query results are typed, not `any[]`
+- **Navigation properties** - `expand` options show available relations
+- **Compile-time errors** - typos in field names caught before runtime
+
+### Regenerating Types
+
+Regenerate types when:
+- You connect a new SAP service
+- The SAP system's schema changes
+- You add new services to your API key
+
+```bash
+# Regenerate all types
+npx s4kit generate-types --api-key sk_live_... --output ./types
 ```
 
 ---

package/dist/index.d.cts

@@ -286,7 +286,7 @@ interface EntityHandler<T = any> {
      * List entities with optional query options
      * @example
      * ```ts
-     * const items = await client.sap.Products.list({ top: 10 });
+     * const items = await client.Products.list({ top: 10 });
      * ```
      */
     list(options?: QueryOptions<T>): Promise<T[]>;
@@ -294,7 +294,7 @@ interface EntityHandler<T = any> {
      * List entities with count
      * @example
      * ```ts
-     * const { value, count } = await client.sap.Products.listWithCount({ top: 10 });
+     * const { value, count } = await client.Products.listWithCount({ top: 10 });
      * console.log(`Showing ${value.length} of ${count} total`);
      * ```
      */
@@ -303,8 +303,8 @@ interface EntityHandler<T = any> {
      * Get single entity by key
      * @example
      * ```ts
-     * const product = await client.sap.Products.get(1);
-     * const partner = await client.sap.A_BusinessPartner.get('BP001');
+     * const product = await client.Products.get(1);
+     * const partner = await client.A_BusinessPartner.get('BP001');
      * ```
      */
     get(id: EntityKey, options?: QueryOptions<T>): Promise<T>;
@@ -312,7 +312,7 @@ interface EntityHandler<T = any> {
      * Count matching entities
      * @example
      * ```ts
-     * const total = await client.sap.Products.count({ filter: "Price gt 100" });
+     * const total = await client.Products.count({ filter: "Price gt 100" });
      * ```
      */
     count(options?: Omit<QueryOptions<T>, 'top' | 'skip' | 'select'>): Promise<number>;
@@ -320,7 +320,7 @@ interface EntityHandler<T = any> {
      * Create a new entity (POST)
      * @example
      * ```ts
-     * const created = await client.sap.Products.create({ Name: 'Widget', Price: 9.99 });
+     * const created = await client.Products.create({ Name: 'Widget', Price: 9.99 });
      * ```
      */
     create(data: Partial<T> | T, options?: QueryOptions<T>): Promise<T>;
@@ -340,7 +340,7 @@ interface EntityHandler<T = any> {
      *
      * @example Composition relationship (works)
      * ```ts
-     * const order = await client.sap.Orders.createDeep({
+     * const order = await client.Orders.createDeep({
      *   OrderID: '001',
      *   Items: [{ Product: 'A', Quantity: 10 }]  // Created with order
      * });
@@ -349,11 +349,11 @@ interface EntityHandler<T = any> {
      * @example Association relationship (use separate calls instead)
      * ```ts
      * // DON'T: This won't create the books - they'll be ignored
-     * await client.sap.Authors.createDeep({ name: 'Author', books: [{...}] });
+     * await client.Authors.createDeep({ name: 'Author', books: [{...}] });
      *
      * // DO: Create separately with FK reference
-     * const author = await client.sap.Authors.create({ name: 'Author' });
-     * await client.sap.Books.createMany([
+     * const author = await client.Authors.create({ name: 'Author' });
+     * await client.Books.createMany([
      *   { title: 'Book 1', author_ID: author.ID }
      * ]);
      * ```
@@ -363,7 +363,7 @@ interface EntityHandler<T = any> {
      * Partial update (PATCH) - only updates specified fields
      * @example
      * ```ts
-     * const updated = await client.sap.Products.update(1, { Price: 12.99 });
+     * const updated = await client.Products.update(1, { Price: 12.99 });
      * ```
      */
     update(id: EntityKey, data: Partial<T>, options?: QueryOptions<T>): Promise<T>;
@@ -371,7 +371,7 @@ interface EntityHandler<T = any> {
      * Full replacement (PUT) - replaces entire entity
      * @example
      * ```ts
-     * const replaced = await client.sap.Products.replace(1, fullProductData);
+     * const replaced = await client.Products.replace(1, fullProductData);
      * ```
      */
     replace(id: EntityKey, data: T, options?: QueryOptions<T>): Promise<T>;
@@ -379,7 +379,7 @@ interface EntityHandler<T = any> {
      * Upsert - create or update based on key
      * @example
      * ```ts
-     * const result = await client.sap.Products.upsert({ ID: 1, Name: 'Widget', Price: 9.99 });
+     * const result = await client.Products.upsert({ ID: 1, Name: 'Widget', Price: 9.99 });
      * ```
      */
     upsert(data: T, options?: QueryOptions<T>): Promise<T>;
@@ -387,7 +387,7 @@ interface EntityHandler<T = any> {
      * Delete entity by key
      * @example
      * ```ts
-     * await client.sap.Products.delete(1);
+     * await client.Products.delete(1);
      * ```
      */
     delete(id: EntityKey, options?: QueryOptions<T>): Promise<void>;
@@ -428,7 +428,7 @@ interface EntityHandler<T = any> {
      * Access navigation property (related entities)
      * @example
      * ```ts
-     * const items = await client.sap.Orders.nav(1, 'Items').list();
+     * const items = await client.Orders.nav(1, 'Items').list();
      * ```
      */
     nav<R = any>(id: EntityKey, property: string): EntityHandler<R>;
@@ -436,7 +436,7 @@ interface EntityHandler<T = any> {
      * Call an OData function (GET operation)
      * @example
      * ```ts
-     * const result = await client.sap.Products.func('GetTopSelling', { count: 10 });
+     * const result = await client.Products.func('GetTopSelling', { count: 10 });
      * ```
      */
     func<R = any>(name: string, params?: Record<string, any>): Promise<R>;
@@ -444,7 +444,7 @@ interface EntityHandler<T = any> {
      * Call an OData action (POST operation)
      * @example
      * ```ts
-     * await client.sap.Orders.action('Approve', { orderId: '001' });
+     * await client.Orders.action('Approve', { orderId: '001' });
      * ```
      */
     action<R = any>(name: string, params?: Record<string, any>): Promise<R>;
@@ -452,7 +452,7 @@ interface EntityHandler<T = any> {
      * Call bound function on specific entity
      * @example
      * ```ts
-     * const total = await client.sap.Orders.boundFunc(1, 'CalculateTotal');
+     * const total = await client.Orders.boundFunc(1, 'CalculateTotal');
      * ```
      */
     boundFunc<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
@@ -460,7 +460,7 @@ interface EntityHandler<T = any> {
      * Call bound action on specific entity
      * @example
      * ```ts
-     * await client.sap.Orders.boundAction('001', 'Submit');
+     * await client.Orders.boundAction('001', 'Submit');
      * ```
      */
     boundAction<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
@@ -469,7 +469,7 @@ interface EntityHandler<T = any> {
      * @example
      * ```ts
      * // Iterate through all pages
-     * for await (const page of client.sap.Products.paginate({ top: 100 })) {
+     * for await (const page of client.Products.paginate({ top: 100 })) {
      *   console.log(`Processing ${page.value.length} items`);
      *   for (const product of page.value) {
      *     // process product
@@ -477,7 +477,7 @@ interface EntityHandler<T = any> {
      * }
      *
      * // Or collect all items
-     * const all = await client.sap.Products.all({ filter: "Active eq true" });
+     * const all = await client.Products.all({ filter: "Active eq true" });
      * ```
      */
     paginate(options?: PaginateOptions<T>): AsyncIterable<ListResponse<T>>;
@@ -485,7 +485,7 @@ interface EntityHandler<T = any> {
      * Get all entities (automatically handles pagination)
      * @example
      * ```ts
-     * const allProducts = await client.sap.Products.all({ filter: "Active eq true" });
+     * const allProducts = await client.Products.all({ filter: "Active eq true" });
      * ```
      */
     all(options?: PaginateOptions<T>): Promise<T[]>;
@@ -507,7 +507,7 @@ type EntityKey = string | number | CompositeKey;
  * Composite key for entities with multiple key fields
  * @example
  * ```ts
- * const item = await client.sap.OrderItems.get({ OrderID: '001', ItemNo: 10 });
+ * const item = await client.OrderItems.get({ OrderID: '001', ItemNo: 10 });
  * ```
  */
 type CompositeKey = Record<string, string | number>;
@@ -868,7 +868,7 @@ declare class S4KitBase {
 }
 /**
  * Create S4Kit client with dynamic entity access
- * Allows: client.Products.list() instead of client.sap.Products.list()
+ * Allows: client.Products.list() instead of client.Products.list()
  *
  * Returns S4KitClientWithDynamicAccess which:
  * - Without generated types: allows any entity access (returns EntityHandler<any>)
@@ -1126,7 +1126,7 @@ declare class FilterBuilder<T = any> {
  *
  * @example
  * ```ts
- * const products = await query(client.sap.Products)
+ * const products = await query(client.Products)
  *   .select('Name', 'Price')
  *   .where('Price', 'gt', 100)
  *   .orderBy('Name', 'asc')

package/dist/index.d.ts

@@ -286,7 +286,7 @@ interface EntityHandler<T = any> {
      * List entities with optional query options
      * @example
      * ```ts
-     * const items = await client.sap.Products.list({ top: 10 });
+     * const items = await client.Products.list({ top: 10 });
      * ```
      */
     list(options?: QueryOptions<T>): Promise<T[]>;
@@ -294,7 +294,7 @@ interface EntityHandler<T = any> {
      * List entities with count
      * @example
      * ```ts
-     * const { value, count } = await client.sap.Products.listWithCount({ top: 10 });
+     * const { value, count } = await client.Products.listWithCount({ top: 10 });
      * console.log(`Showing ${value.length} of ${count} total`);
      * ```
      */
@@ -303,8 +303,8 @@ interface EntityHandler<T = any> {
      * Get single entity by key
      * @example
      * ```ts
-     * const product = await client.sap.Products.get(1);
-     * const partner = await client.sap.A_BusinessPartner.get('BP001');
+     * const product = await client.Products.get(1);
+     * const partner = await client.A_BusinessPartner.get('BP001');
      * ```
      */
     get(id: EntityKey, options?: QueryOptions<T>): Promise<T>;
@@ -312,7 +312,7 @@ interface EntityHandler<T = any> {
      * Count matching entities
      * @example
      * ```ts
-     * const total = await client.sap.Products.count({ filter: "Price gt 100" });
+     * const total = await client.Products.count({ filter: "Price gt 100" });
      * ```
      */
     count(options?: Omit<QueryOptions<T>, 'top' | 'skip' | 'select'>): Promise<number>;
@@ -320,7 +320,7 @@ interface EntityHandler<T = any> {
      * Create a new entity (POST)
      * @example
      * ```ts
-     * const created = await client.sap.Products.create({ Name: 'Widget', Price: 9.99 });
+     * const created = await client.Products.create({ Name: 'Widget', Price: 9.99 });
      * ```
      */
     create(data: Partial<T> | T, options?: QueryOptions<T>): Promise<T>;
@@ -340,7 +340,7 @@ interface EntityHandler<T = any> {
      *
      * @example Composition relationship (works)
      * ```ts
-     * const order = await client.sap.Orders.createDeep({
+     * const order = await client.Orders.createDeep({
      *   OrderID: '001',
      *   Items: [{ Product: 'A', Quantity: 10 }]  // Created with order
      * });
@@ -349,11 +349,11 @@ interface EntityHandler<T = any> {
      * @example Association relationship (use separate calls instead)
      * ```ts
      * // DON'T: This won't create the books - they'll be ignored
-     * await client.sap.Authors.createDeep({ name: 'Author', books: [{...}] });
+     * await client.Authors.createDeep({ name: 'Author', books: [{...}] });
      *
      * // DO: Create separately with FK reference
-     * const author = await client.sap.Authors.create({ name: 'Author' });
-     * await client.sap.Books.createMany([
+     * const author = await client.Authors.create({ name: 'Author' });
+     * await client.Books.createMany([
      *   { title: 'Book 1', author_ID: author.ID }
      * ]);
      * ```
@@ -363,7 +363,7 @@ interface EntityHandler<T = any> {
      * Partial update (PATCH) - only updates specified fields
      * @example
      * ```ts
-     * const updated = await client.sap.Products.update(1, { Price: 12.99 });
+     * const updated = await client.Products.update(1, { Price: 12.99 });
      * ```
      */
     update(id: EntityKey, data: Partial<T>, options?: QueryOptions<T>): Promise<T>;
@@ -371,7 +371,7 @@ interface EntityHandler<T = any> {
      * Full replacement (PUT) - replaces entire entity
      * @example
      * ```ts
-     * const replaced = await client.sap.Products.replace(1, fullProductData);
+     * const replaced = await client.Products.replace(1, fullProductData);
      * ```
      */
     replace(id: EntityKey, data: T, options?: QueryOptions<T>): Promise<T>;
@@ -379,7 +379,7 @@ interface EntityHandler<T = any> {
      * Upsert - create or update based on key
      * @example
      * ```ts
-     * const result = await client.sap.Products.upsert({ ID: 1, Name: 'Widget', Price: 9.99 });
+     * const result = await client.Products.upsert({ ID: 1, Name: 'Widget', Price: 9.99 });
      * ```
      */
     upsert(data: T, options?: QueryOptions<T>): Promise<T>;
@@ -387,7 +387,7 @@ interface EntityHandler<T = any> {
      * Delete entity by key
      * @example
      * ```ts
-     * await client.sap.Products.delete(1);
+     * await client.Products.delete(1);
      * ```
      */
     delete(id: EntityKey, options?: QueryOptions<T>): Promise<void>;
@@ -428,7 +428,7 @@ interface EntityHandler<T = any> {
      * Access navigation property (related entities)
      * @example
      * ```ts
-     * const items = await client.sap.Orders.nav(1, 'Items').list();
+     * const items = await client.Orders.nav(1, 'Items').list();
      * ```
      */
     nav<R = any>(id: EntityKey, property: string): EntityHandler<R>;
@@ -436,7 +436,7 @@ interface EntityHandler<T = any> {
      * Call an OData function (GET operation)
      * @example
      * ```ts
-     * const result = await client.sap.Products.func('GetTopSelling', { count: 10 });
+     * const result = await client.Products.func('GetTopSelling', { count: 10 });
      * ```
      */
     func<R = any>(name: string, params?: Record<string, any>): Promise<R>;
@@ -444,7 +444,7 @@ interface EntityHandler<T = any> {
      * Call an OData action (POST operation)
      * @example
      * ```ts
-     * await client.sap.Orders.action('Approve', { orderId: '001' });
+     * await client.Orders.action('Approve', { orderId: '001' });
      * ```
      */
     action<R = any>(name: string, params?: Record<string, any>): Promise<R>;
@@ -452,7 +452,7 @@ interface EntityHandler<T = any> {
      * Call bound function on specific entity
      * @example
      * ```ts
-     * const total = await client.sap.Orders.boundFunc(1, 'CalculateTotal');
+     * const total = await client.Orders.boundFunc(1, 'CalculateTotal');
      * ```
      */
     boundFunc<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
@@ -460,7 +460,7 @@ interface EntityHandler<T = any> {
      * Call bound action on specific entity
      * @example
      * ```ts
-     * await client.sap.Orders.boundAction('001', 'Submit');
+     * await client.Orders.boundAction('001', 'Submit');
      * ```
      */
     boundAction<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
@@ -469,7 +469,7 @@ interface EntityHandler<T = any> {
      * @example
      * ```ts
      * // Iterate through all pages
-     * for await (const page of client.sap.Products.paginate({ top: 100 })) {
+     * for await (const page of client.Products.paginate({ top: 100 })) {
      *   console.log(`Processing ${page.value.length} items`);
      *   for (const product of page.value) {
      *     // process product
@@ -477,7 +477,7 @@ interface EntityHandler<T = any> {
      * }
      *
      * // Or collect all items
-     * const all = await client.sap.Products.all({ filter: "Active eq true" });
+     * const all = await client.Products.all({ filter: "Active eq true" });
      * ```
      */
     paginate(options?: PaginateOptions<T>): AsyncIterable<ListResponse<T>>;
@@ -485,7 +485,7 @@ interface EntityHandler<T = any> {
      * Get all entities (automatically handles pagination)
      * @example
      * ```ts
-     * const allProducts = await client.sap.Products.all({ filter: "Active eq true" });
+     * const allProducts = await client.Products.all({ filter: "Active eq true" });
      * ```
      */
     all(options?: PaginateOptions<T>): Promise<T[]>;
@@ -507,7 +507,7 @@ type EntityKey = string | number | CompositeKey;
  * Composite key for entities with multiple key fields
  * @example
  * ```ts
- * const item = await client.sap.OrderItems.get({ OrderID: '001', ItemNo: 10 });
+ * const item = await client.OrderItems.get({ OrderID: '001', ItemNo: 10 });
  * ```
  */
 type CompositeKey = Record<string, string | number>;
@@ -868,7 +868,7 @@ declare class S4KitBase {
 }
 /**
  * Create S4Kit client with dynamic entity access
- * Allows: client.Products.list() instead of client.sap.Products.list()
+ * Allows: client.Products.list() instead of client.Products.list()
  *
  * Returns S4KitClientWithDynamicAccess which:
  * - Without generated types: allows any entity access (returns EntityHandler<any>)
@@ -1126,7 +1126,7 @@ declare class FilterBuilder<T = any> {
  *
  * @example
  * ```ts
- * const products = await query(client.sap.Products)
+ * const products = await query(client.Products)
  *   .select('Name', 'Price')
  *   .where('Price', 'gt', 100)
  *   .orderBy('Name', 'asc')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s4kit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "The lightweight, type-safe SDK for SAP S/4HANA",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",