Your application calls the operation. The profile handles the connection.

An explicit profile. A bounded interactive request.

Authentication belongs on your backend. This proposed package is not published, and none of these runtime endpoints exist on this website. The example records operations and customers resource belong to the fictional vendor's contract; they are not a platform-imposed schema.

A request-response read can wait up to a bounded timeoutMs: 8000. The intended result includes the vendor-agreed data shape and a traceId. A timeout describes what the caller observed; it does not prove the destination did nothing.

// Proposed SDK — illustrative API design; not a published package.
const invokation = new Invokation({
  apiKey: process.env.INVOKATION_API_KEY
});

// The profile handles downstream authentication.
const result = await invokation.request({
  profile: "stripe.production",
  operation: "payments.getStatus",
  input: { paymentId: "payment_demo_123" },
  timeoutMs: 8000
});

A company provider profile needs no client identity. payments.getStatus is a fictional application operation translated by its adapter, not a native Stripe endpoint. Downstream credentials are resolved by the profile; the caller does not fetch or pass provider tokens.

// Proposed SDK — package and API are not yet available.
const invokation = new Invokation({
  apiKey: process.env.INVOKATION_API_KEY
});

const result = await invokation.request({
  profile: "client-alpha.production",
  operation: "records.list",
  input: { resource: "customers", limit: 20 },
  timeoutMs: 8000
});

console.log(result.data, result.traceId);

Compare managed authentication strategies and renewal for API keys, OAuth client credentials, delegated grants, and custom token endpoints.

Acceptance is not completion

Use queued execution for background updates, scheduled synchronization, or work that does not need to finish inside an interactive request. Enqueue returns a run reference. Inspect the run separately for attempt history, delivery status, and final outcome.

// Proposed SDK — package and API are not yet available.
const run = await invokation.enqueue({
  profile: "client-alpha.production",
  operation: "records.upsert",
  input: {
    resource: "customers",
    record: {
      id: "REC-123",
      displayName: "Example account",
      status: "active"
    }
  },
  idempotencyKey: "customer-update-987"
});

// Accepted does not mean completed.
const status = await invokation.runs.get(run.id);

Retries follow the operation's configured policy and destination behavior. Preserve a logical action's idempotency key across its attempts. Attaching a key alone does not make arbitrary external writes exactly-once; destination enforcement and retention matter.

The same model over REST

The explanatory REST design uses a request resource for interactive execution and a run resource for queued execution. A successful queue acceptance would return 202 Accepted with a run reference, not a claim that the update completed.

# API design preview — these are not live endpoints.
POST /v1/requests
Authorization: Bearer <server-side credential>
Content-Type: application/json

{
  "profile": "client-alpha.production",
  "operation": "records.list",
  "input": { "resource": "customers", "limit": 20 },
  "timeoutMs": 8000
}

# Queue acceptance is not completion.
POST /v1/runs
Authorization: Bearer <server-side credential>
Content-Type: application/json

{
  "profile": "client-alpha.production",
  "operation": "records.upsert",
  "input": {
    "resource": "customers",
    "record": {
      "id": "REC-123",
      "displayName": "Example account",
      "status": "active"
    }
  },
  "idempotencyKey": "customer-update-987"
}

# Proposed response: 202 Accepted
# { "id": "run_demo_01", "status": "accepted" }
GET /v1/runs/run_demo_01
Authorization: Bearer <server-side credential>
# Inspect attempts and final outcome separately.

Version the provider or customer implementation

A profile selects an optional customer alias, environment, pinned adapter, authentication strategy, mapping version, credential reference, and egress policy reference. The credential reference is not a usable credential. Keep separate sandbox and production profiles and test before promoting a configuration.

{
  "id": "client-beta.production",
  "customerAlias": "Client Beta",
  "environment": "production",
  "adapter": "soap-records@2",
  "mappingVersion": "3.2.0",
  "credentialRef": "secrets/client-beta/production",
  "egressPolicyRef": "egress/shared-eu/v1",
  "operations": [
    "records.list",
    "records.upsert"
  ],
  "endpoint": "https://beta.example.com/services/records"
}

Useful errors without exposed secrets

Normalize categories so application code can distinguish validation, authorization, unsupported operations, rate limits, and timeouts. Preserve redacted original context for authorized diagnosis. A mapping-validation failure should not be retried unchanged.

try {
  const result = await invokation.request({
    profile: "client-alpha.production",
    operation: "records.list",
    input: { resource: "customers", limit: 20 },
    timeoutMs: 8000
  });
} catch (error) {
  // Proposed structured error. Never log raw credentials.
  // { category: "mapping_validation", retryable: false,
  //   field: "status", traceId: "trace_demo_01",
  //   original: { payload: "[REDACTED]" } }
  reportIntegrationFailure(error.category, error.traceId);
}

The intended local-to-production workflow

1. Define operation schemas and capability limits in configuration tracked in Git.
2. Build or adapt a template and add synthetic fixtures for valid results and failure cases.
3. Test locally through a future CLI workflow, with secret references and environment-specific overrides.
4. Run contract and fixture checks in CI, then review a versioned profile change.
5. Test the approved sandbox route and authorization, and promote production references deliberately.
6. Inspect traces and attempts centrally; review destination state and original versions before replay.

This describes the intended developer experience, not commands for a published CLI. For a deeper implementation discussion, read customer-specific SaaS integrations and safer recovery.