@abapify/adt-client 0.0.0 → 0.3.5

package/README.md

@@ -1,3 +1,285 @@
 # @abapify/adt-client
 
-Placeholder. The real release is published via CI/CD.
+[![version](https://img.shields.io/github/package-json/v/abapify/adt-cli?filename=packages/adt-client/package.json)](https://github.com/abapify/adt-cli/pkgs/npm/%40abapify%2Fadt-client)
+
+**Contract-driven SAP ADT REST client** — uses `speci` + `ts-xsd` for full type safety.
+
+## Why v2?
+
+This package replaces the legacy `adt-client` with a **contract-first design**:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      adt-client                               │
+│              (HTTP Client + Request Execution)                   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      adt-contracts                               │
+│         (REST API Contracts using speci + ts-xsd)                │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     adt-schemas                              │
+│        (TypeScript schemas from SAP XSD definitions)             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits over v1:**
+
+- ✅ **Type-safe from XSD** - Types generated from official SAP schemas
+- ✅ **Contract-first** - API contracts define the interface
+- ✅ **Zero manual types** - No hand-written type definitions
+- ✅ **Easy to extend** - Add endpoints by defining contracts
+- ✅ **Testable** - Contracts are pure data, easy to mock
+
+## Features
+
+- ✅ **Contract-driven** - Uses `speci` + `ts-xsd` contracts
+- ✅ **Full type inference** - Types flow from XSD to response
+- ✅ **Zero dependencies** - Only uses native fetch API
+- ✅ **Clean API** - Arrow-function contracts
+- ✅ **Promise-based** - Modern async/await API
+
+## Installation
+
+```bash
+bun add @abapify/adt-client
+```
+
+## Quick Start
+
+```typescript
+import { createAdtClient } from '@abapify/adt-client';
+
+// Create client
+const client = createAdtClient({
+  baseUrl: 'https://sap-system.com:8000',
+  username: 'YOUR_USER',
+  password: 'YOUR_PASS',
+  client: '100',
+  language: 'EN',
+});
+
+// Get complete class with all includes
+const classObj = await client.getClass('ZCL_MY_CLASS');
+console.log(classObj.metadata.description);
+console.log(classObj.includes.main);
+console.log(classObj.includes.definitions);
+console.log(classObj.includes.implementations);
+
+// Update main source
+await client.updateMainSource('ZCL_MY_CLASS', newSource);
+```
+
+## API Reference
+
+### Client Creation
+
+```typescript
+createAdtClient(config: AdtConnectionConfig): AdtClient
+```
+
+**Config:**
+
+- `baseUrl` - SAP system URL (e.g., `https://sap-system.com:8000`)
+- `username` - SAP username
+- `password` - SAP password
+- `client` - SAP client (optional, e.g., `'100'`)
+- `language` - SAP language (optional, e.g., `'EN'`)
+
+### Class Operations
+
+#### Get Complete Class
+
+```typescript
+getClass(className: string): Promise<ClassObject>
+```
+
+Returns class metadata and all includes (main, definitions, implementations, macros, testclasses).
+
+#### Get Metadata Only
+
+```typescript
+getMetadata(className: string): Promise<ClassMetadata>
+```
+
+Returns class metadata (name, description, package, etc.).
+
+#### Get All Includes
+
+```typescript
+getIncludes(className: string): Promise<ClassIncludes>
+```
+
+Returns all class source includes.
+
+#### Get Specific Include
+
+```typescript
+getInclude(className: string, includeType: 'main' | 'definitions' | 'implementations' | 'macros' | 'testclasses'): Promise<string>
+```
+
+Returns specific include source code.
+
+#### Update Main Source
+
+```typescript
+updateMainSource(className: string, source: string): Promise<OperationResult>
+```
+
+Updates the main class source code.
+
+#### Create Class
+
+```typescript
+createClass(className: string, metadata: Partial<ClassMetadata>): Promise<OperationResult>
+```
+
+Creates a new class with specified metadata.
+
+#### Delete Class
+
+```typescript
+deleteClass(className: string): Promise<OperationResult>
+```
+
+Deletes a class.
+
+#### Lock/Unlock
+
+```typescript
+lockClass(className: string): Promise<string>
+unlockClass(className: string, lockHandle: string): Promise<OperationResult>
+```
+
+Lock and unlock class for editing.
+
+## Types
+
+### ClassMetadata
+
+```typescript
+interface ClassMetadata {
+  name: string;
+  description?: string;
+  packageName?: string;
+  responsible?: string;
+  createdBy?: string;
+  createdAt?: string;
+  changedBy?: string;
+  changedAt?: string;
+  final?: boolean;
+  abstract?: boolean;
+  visibility?: 'public' | 'protected' | 'private';
+}
+```
+
+### ClassIncludes
+
+```typescript
+interface ClassIncludes {
+  main?: string;
+  definitions?: string;
+  implementations?: string;
+  macros?: string;
+  testclasses?: string;
+}
+```
+
+### ClassObject
+
+```typescript
+interface ClassObject {
+  metadata: ClassMetadata;
+  includes: ClassIncludes;
+}
+```
+
+## Examples
+
+### Read and Modify Class
+
+```typescript
+// Get class
+const classObj = await client.getClass('ZCL_MY_CLASS');
+
+// Modify source
+const newSource = classObj.includes.main?.replace('OLD_TEXT', 'NEW_TEXT');
+
+// Update
+if (newSource) {
+  await client.updateMainSource('ZCL_MY_CLASS', newSource);
+}
+```
+
+### Create New Class
+
+```typescript
+await client.createClass('ZCL_NEW_CLASS', {
+  description: 'My new class',
+  packageName: 'ZPACKAGE',
+  visibility: 'public',
+  final: false,
+  abstract: false,
+});
+```
+
+### Lock, Edit, Unlock Pattern
+
+```typescript
+// Lock class
+const lockHandle = await client.lockClass('ZCL_MY_CLASS');
+
+try {
+  // Edit class
+  await client.updateMainSource('ZCL_MY_CLASS', newSource);
+} finally {
+  // Always unlock
+  await client.unlockClass('ZCL_MY_CLASS', lockHandle);
+}
+```
+
+## Architecture
+
+### Two-Layer Design
+
+```typescript
+const client = createAdtClient({...});
+
+// Layer 1: Low-level contracts (direct ADT REST access)
+client.adt.core.http.sessions.getSession()
+client.adt.cts.transportrequests.getTransport(id)
+
+// Layer 2: High-level services (business logic)
+client.services.transports.importAndActivate(transportId)  // Future
+
+// Utility: Raw HTTP for debugging
+client.fetch('/arbitrary/endpoint', { method: 'GET' })
+```
+
+**Contracts** - Thin, declarative HTTP definitions with 1:1 mapping to SAP ADT endpoints
+**Services** - Business logic orchestration combining multiple contract calls
+
+## Comparison with adt-client v1
+
+| Feature           | v1 (Legacy)   | v2 (New)           |
+| ----------------- | ------------- | ------------------ |
+| **Type Safety**   | Manual types  | Generated from XSD |
+| **Architecture**  | Service-based | Contract-first     |
+| **Dependencies**  | Many          | Zero               |
+| **Extensibility** | Complex       | Add contracts      |
+| **Testing**       | Difficult     | Easy (pure data)   |
+
+## Related Packages
+
+- **[adt-contracts](../adt-contracts)** - REST API contracts (speci + ts-xsd)
+- **[adt-schemas](../adt-schemas)** - TypeScript schemas from SAP XSD
+- **[speci](../speci)** - Contract specification system
+- **[ts-xsd](../ts-xsd)** - XSD → TypeScript generation
+
+## License
+
+MIT

package/package.json

@@ -1,5 +1,33 @@
 {
   "name": "@abapify/adt-client",
-  "version": "0.0.0",
-  "description": "Placeholder — real package is published via CI/CD (trusted publishing)."
-}
+  "version": "0.3.5",
+  "description": "Minimalistic speci-based ADT client for SAP ABAP Development Tools",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@abapify/logger": "0.3.5",
+    "@abapify/adt-contracts": "0.3.5",
+    "@abapify/adt-schemas": "0.3.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abapify/adt-cli.git",
+    "directory": "packages/adt-client"
+  },
+  "homepage": "https://github.com/abapify/adt-cli/tree/main/packages/adt-client#readme",
+  "bugs": {
+    "url": "https://github.com/abapify/adt-cli/issues"
+  }
+}