@inklok/api-spec 7.2.0 → 7.2.2

package/README.md

@@ -1,134 +1,145 @@
-# OpenAPI Specification — OpaqueInk Core API
+# Inklok API Specification
 
-This directory contains the **canonical OpenAPI v3 specification** for OpaqueInk core Lambda endpoints.
+Canonical OpenAPI v3 specification for the Inklok public API.
 
-## Ownership
+This package contains the API contract used by Inklok developer tools, SDKs, and integrations. It defines available endpoints, request and response schemas, authentication requirements, and shared API components.
 
-**This specification is owned by `opaqueink_infra` and is the single source of truth for API contracts.**
+## Installation
 
-- API Gateway routes are generated from this specification
-- Terraform uses this spec to configure API Gateway integrations
-- `opaqueink_core` consumes this spec but does not own it
-- All API changes must be made here first, then propagated to implementations
+Install the specification package from npm:
 
-## API URL Configuration
+```bash
+npm install @inklok/api-spec
+```
+
+## Usage
+
+The specification can be used to:
+
+- Generate API clients
+- Generate strongly typed models
+- Validate requests and responses
+- Build custom integrations
+- Keep integrations aligned with the Inklok API contract
 
-**⚠️ IMPORTANT: The API server URL is configured in `openapi.yaml` under the `servers` section.**
+Example:
 
-To update the API Gateway URL, edit the `servers` section in `openapi.yaml`:
+```js
+import fs from "node:fs";
 
-```yaml
-servers:
-  - url: https://YOUR-API-GATEWAY-URL/prod
-    description: Production API Gateway
+const openapi = fs.readFileSync(
+  "node_modules/@inklok/api-spec/openapi.yaml",
+  "utf8"
+);
+
+console.log(openapi);
 ```
 
-The Scalar documentation build script automatically reads this URL from the OpenAPI spec, so updating it here will update the documentation as well.
+## API Documentation
 
-**Current API URL:** `https://4rh4k08rih.execute-api.us-east-2.amazonaws.com/prod`
+The interactive API reference is available at:
 
-## Structure
+https://docs.inklok.com/docs/api-reference
 
-- **`openapi.yaml`** - Complete OpenAPI v3 specification with inline component references
-- **`components/`** - Modular component definitions (for maintainability, but consolidated into openapi.yaml for API Gateway)
-  - `schemas.yaml` - Data model schemas
-  - `responses.yaml` - Standard response definitions
-  - `security.yaml` - Security scheme definitions
-- **`package.json`** - Node.js dependencies for validation and deployment
+The API reference includes:
 
-## Building and Validation
+- Endpoint documentation
+- Authentication requirements
+- Request and response schemas
+- Example requests and responses
+- Interactive API exploration
 
-### Install Dependencies
+## API Endpoint
 
-```bash
-cd api
-npm install
-```
+The production Inklok API endpoint is:
 
-### Validate the Specification
+https://api.inklok.com
 
-**Using basic validation:**
-```bash
-npm install
-npm run validate-basic
-# or directly:
-node validate-basic.js
-```
+SDK clients and integrations should use this as the API base URL.
 
-**Using the validation script** (includes multiple fallbacks):
-```bash
-chmod +x validate.sh
-./validate.sh
-```
+## Package Contents
 
-### Build Documentation
+This package contains:
 
-```bash
-npm run build-docs
+```text
+openapi.yaml
+components/
+  schemas.yaml
+  responses.yaml
+  security.yaml
+package.json
 ```
 
-This builds the Scalar API documentation with interactive "Try-It-Out" functionality.
+## Specification Details
 
-### Deploy Documentation
+This package follows the OpenAPI specification format.
 
-```bash
-export S3_BUCKET_NAME="your-bucket-name"
-export CLOUDFRONT_DISTRIBUTION_ID="your-distribution-id"
-npm run deploy-docs
-```
+It defines:
+
+- API paths and operations
+- Request parameters
+- Request bodies
+- Response schemas
+- Authentication schemes
+- Shared response definitions
 
-This builds and deploys the documentation to S3/CloudFront.
+## Authentication
 
-## Integration with API Gateway
+The Inklok API uses authenticated requests.
 
-The `openapi.yaml` file uses `x-amazon-apigateway-*` extensions to define:
+Supported authentication methods include:
 
-- Lambda integrations (`x-amazon-apigateway-integration`)
-- Authentication configuration
-- Request/response mappings
-- CORS behavior
+- User access tokens
+- Inklok API keys
 
-Terraform in `../api_gateway/` imports this specification to configure API Gateway.
+See the API reference for authentication details and examples.
 
 ## API Versioning
 
-**⚠️ HARD REQUIREMENT: All new endpoints MUST be versioned using `/v1/` path prefix.**
+The Inklok API uses versioned endpoints.
+
+New API capabilities are introduced using version prefixes:
+
+```text
+/v1/agreements
+/v1/documents
+```
+
+Applications should use the versioned API paths documented in the API reference.
+
+## Validation
+
+To validate the specification locally:
 
-See [API_VERSIONING.md](API_VERSIONING.md) for the complete versioning strategy and requirements.
+```bash
+npm install
+npm run validate-basic
+```
 
-**Quick Reference:**
-- ✅ New endpoint: `/v1/orgs/{orgId}/members`
-- ❌ Missing version: `/orgs/{orgId}/members` (not allowed for new endpoints)
+## Consuming Updates
 
-## Adding New Endpoints
+The package is published as:
 
-1. **⚠️ Ensure path includes `/v1/` prefix** (see [API_VERSIONING.md](API_VERSIONING.md))
-2. **Add the path definition** to `openapi.yaml` under `paths:`
-3. **Add the Lambda integration** using `x-amazon-apigateway-integration` extension
-4. **Add schemas** to `components/schemas` if needed
-5. **Add responses** using component references (e.g., `$ref: '#/components/responses/Unauthorized'`)
-6. **Run validation**: `npm run validate-basic`
-7. **Update Terraform** in `../api_gateway/` to reference the new Lambda function
+```text
+@inklok/api-spec
+```
+
+Install:
 
-## Editing Guidelines
+```bash
+npm install @inklok/api-spec
+```
 
-- **⚠️ Versioning**: All new endpoints MUST use `/v1/` path prefix (see [API_VERSIONING.md](API_VERSIONING.md))
-- **Operation IDs** must be unique and descriptive (use kebab-case)
-- **All endpoints** require Bearer JWT authentication (defined globally)
-- **Error responses** should use component references from `components/responses`
-- **Schemas** should be defined in `components/schemas` and referenced
-- **Tags** should be used consistently to group related operations
+New versions are released as the Inklok API evolves.
 
-## Publishing to npm
+## Related Resources
 
-This package is published to the public npm registry as `@inklok/api-spec` so `opaqueink_core` and other repos can consume it for codegen and type generation.
+API Reference:
+https://docs.inklok.com/docs/api-reference
 
-- **Manual publish:** See [PUBLISH.md](PUBLISH.md) for setup and `npm publish` instructions
-- **CI publish:** Create a GitHub Release to trigger `.github/workflows/publish-api-spec.yml`
-- **Consuming:** `npm install @inklok/api-spec`
+Inklok:
+https://inklok.com
 
-## Reference
+## License
 
-- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
-- [API Gateway OpenAPI Extensions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
-- [Scalar API Reference](https://github.com/scalar/scalar)
+See package metadata for licensing information.

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.2.0"
+  version: "7.2.2"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -2480,6 +2480,18 @@ paths:
                 properties:
                   execution_id:
                     type: string
+                  agreement_title:
+                    type: string
+                    nullable: true
+                    description: Human-readable title for this agreement.
+                  agreement_message:
+                    type: string
+                    nullable: true
+                    description: Shared message from the sender for all recipients.
+                  recipient_message:
+                    type: string
+                    nullable: true
+                    description: Private message for the authenticated signer only.
                   version:
                     type: string
                     description: Rendering engine version for this agreement
@@ -4694,11 +4706,26 @@ components:
         name:
           type: string
           nullable: true
+        recipientMessage:
+          type: string
+          nullable: true
+          maxLength: 5000
+          description: Optional private message visible only to this recipient.
 
     CreateExecutionRequest:
       type: object
-      required: [participants, crypto]
+      required: [agreementTitle, participants, crypto]
       properties:
+        agreementTitle:
+          type: string
+          minLength: 1
+          maxLength: 160
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          maxLength: 5000
+          description: Optional shared message visible to all recipients.
         participants:
           type: array
           minItems: 1
@@ -5047,6 +5074,16 @@ components:
           type: integer
           minimum: 1
           readOnly: true
+        agreementTitle:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Shared message from the sender for all recipients.
         pdfEngineVersion:
           type: integer
           minimum: 1
@@ -5092,6 +5129,7 @@ components:
           createdAt,
           updatedAt,
           pdfEngineVersion,
+          agreementTitle,
           participants,
           placeholderValues,
         ]
@@ -5107,6 +5145,16 @@ components:
         status:
           $ref: '#/components/schemas/ExecutionStatus'
           readOnly: true
+        agreementTitle:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Human-readable title for this agreement.
+        agreementMessage:
+          type: string
+          nullable: true
+          readOnly: true
+          description: Shared message from the sender for all recipients.
         createdAt:
           type: string
           format: date-time
@@ -5173,6 +5221,10 @@ components:
         color:
           type: string
           nullable: true
+        recipientMessage:
+          type: string
+          nullable: true
+          description: Private message for this recipient. Signer-scoped responses only include the current signer's message.
 
     ExecutionParticipantSearchResult:
       type: object

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.2.0",
-  "description": "OpenAPI specification for OpaqueInk Core API (owned by opaqueink_infra)",
+  "version": "7.2.2",
+  "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
+  "license": "MIT",
+  "keywords": [
+    "inklok",
+    "api",
+    "openapi",
+    "sdk",
+    "typescript",
+    "integration",
+    "developer"
+  ],
   "files": [
     "openapi.yaml",
     "components/",
@@ -22,11 +32,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ryan-m-erickson/opaqueink_infra.git",
-    "directory": "api"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"