Skip to content

Crafter — Reusable Consumed Objects

Coming soon

Crafter is not yet released. This page describes a planned feature for sharing consumed adapters across capabilities. Crafter ships in every edition of the Naftiko Fleet; reusable consumed objects with a shared catalog are a Standard-edition feature.

The problem

The consumes block of a single SaaS vendor (GitHub, Slack, Notion, Stripe) is enormous — dozens to hundreds of resources, operations, output parameter mappings, and authentication wiring. Duplicating that across capabilities is toil and a maintenance trap: when the upstream API changes, all duplicates drift.

The solution

Crafter provides a shared consumes library: import a vendor's API once, save it as a reusable artifact, and reference it from any number of capabilities with $ref.

# In your capability:
ikanos: "1.0.0-alpha3"
capability:
  consumes:
    - from: "library://github/v2025-04"     # imported once, reused everywhere
      import: github
    - from: "library://slack/v2"
      import: slack

Under the hood:

Element Behavior
Library entry A standalone consumes document (no capability: root)
Versioning Each library entry has a semver-pinned reference
Local cache Crafter caches resolved $ref targets for offline editing
CI resolution polychro lint and ikanos validate follow $ref transparently

Library sources

Source URI scheme Use case
Workspace library://... Team-shared consumed adapters
Local file file://... Project-local sharing
Git repo git://github.com/org/library.git#path Cross-team sharing
Hosted catalog naftiko-catalog://github/... Curated, published library

Creating a reusable consumed object

In Crafter:

  1. Right-click a consumes adapter → "Save to library"
  2. Pick a target library and version label
  3. Crafter writes a standalone consumes document (no capability: root)
  4. The original capability rewrites its inline block as a $ref

The result is a standalone consumed document:

# library/github/v2025-04.ikanos.yml
ikanos: "1.0.0-alpha3"
info:
  display: "GitHub REST API consumes"
  description: "Reusable GitHub REST API adapter"

consumes:                                   # ← root-level, no `capability:`
  - namespace: github
    type: http
    baseUri: "https://api.github.com"
    authentication: { type: bearer, token: "GITHUB_TOKEN" }
    resources:                              # alpha3 — keyed map
      users:
        path: "/users/{username}"
        operations:
          get-user:
            method: GET

Updates and drift detection

When a library entry is updated (new version published), Crafter flags dependents and offers a guided upgrade — diffing operation signatures and output parameter mappings so you can review changes before adopting.

Standard vs Community

The shared-consumes mechanism ($ref resolution) is defined at the schema level and works in any edition. Crafter's library UI, versioning, and drift detection are Standard-edition features.