# discover-integrations

**Description:** Discover the Naftiko-capability integrations published per API provider on apis.io. These are declarative YAML integration manifests — agent-runnable via Docker + the Naftiko Framework — that replace static "integrations pages" with executable artifacts.

## When to use this skill

Use this skill when the user:
- Asks how an API provider integrates with another system ("how does Stripe integrate with Shopify?").
- Wants to **run** an integration, not just read about it.
- Wants a machine-readable list of a provider's integration patterns.
- Mentions Naftiko capabilities or executable integrations.

If the user just wants a marketing list of partners, hit the provider's page directly. Use this skill when the goal is *acting* on an integration, not browsing one.

## What "integrations" means on apis.io

Each API provider on apis.io may publish an `integrations/` folder in its upstream
`api-evangelist/<provider>` GitHub repo. Each YAML in that folder is a **Naftiko
capability**: a declarative, executable description of one real integration workflow.

Unlike a partner directory, every integration here is:

1. **Addressable** — has a stable raw URL.
2. **Executable** — runs under the Naftiko Framework (Docker).
3. **Self-describing** — names the providers, trigger, steps, inputs, and outputs in YAML.
4. **Agent-runnable** — an LLM can read it, plan against it, and invoke it without bespoke code.

The capability YAML schema is small (see the example at the bottom of any integrations page).

## Where to find them

| Surface | URL pattern |
|---|---|
| Per-provider page | `https://providers.apis.io/providers/<slug>/integrations/` |
| Raw YAML folder   | `https://github.com/api-evangelist/<slug>/tree/main/integrations` |
| GitHub Contents API | `https://api.github.com/repos/api-evangelist/<slug>/contents/integrations` |
| Raw file URL | `https://raw.githubusercontent.com/api-evangelist/<slug>/refs/heads/main/integrations/<file>.yaml` |

Use the Contents API to enumerate; use the raw URL to fetch the YAML.

## Recipe — list a provider's integrations

```python
import json, urllib.request, yaml

def list_integrations(provider_slug):
    """Return parsed Naftiko capabilities for one provider, or [] if none published yet."""
    api = f"https://api.github.com/repos/api-evangelist/{provider_slug}/contents/integrations"
    req = urllib.request.Request(api, headers={"Accept": "application/vnd.github+json"})
    try:
        with urllib.request.urlopen(req) as r:
            entries = json.load(r)
    except urllib.error.HTTPError as e:
        if e.code == 404:
            return []  # provider hasn't published an integrations/ folder yet
        raise

    out = []
    for entry in entries:
        if entry["type"] != "file" or not entry["name"].lower().endswith((".yaml", ".yml")):
            continue
        with urllib.request.urlopen(entry["download_url"]) as r:
            cap = yaml.safe_load(r.read().decode("utf-8"))
        cap["_source"] = entry["html_url"]
        cap["_raw"] = entry["download_url"]
        cap["_filename"] = entry["name"]
        out.append(cap)
    return out
```

## Recipe — find integrations across providers

When the user asks "which providers integrate with Shopify?", scan capability YAMLs for
`providers:` containing the target system, OR look for `call:` steps that reference it.

```python
def find_integrations_with(target_system, providers_to_scan):
    matches = []
    for slug in providers_to_scan:
        for cap in list_integrations(slug):
            participants = set(cap.get("providers", []))
            participants.update(
                step.get("call", "").split(".")[0]
                for step in cap.get("steps", [])
                if isinstance(step, dict)
            )
            if target_system in participants:
                matches.append((slug, cap))
    return matches
```

Get the candidate `providers_to_scan` list from `discover-apis-io` (any provider listed in
the apis.io network may publish integrations).

## Running a capability

Once you have a capability YAML, the Naftiko Framework runs it:

```bash
docker run --rm \
  -v $PWD/credentials.env:/credentials.env \
  naftiko/fleet run \
  https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/integrations/<capability>.yaml
```

The framework lives at <https://github.com/naftiko/fleet>. It handles:
- Credential injection from env files
- Trigger registration (webhook, schedule, manual)
- Step orchestration (call, transform, condition, branch)
- Output capture

## What to surface to the user

After listing, return per integration:
- **Name** — `cap.name`
- **Description** — `cap.description`
- **Participants** — `cap.providers` (the systems involved)
- **Trigger** — `cap.trigger.type` and `cap.trigger.source`
- **Step count** — `len(cap.steps)`
- **Run command** — the docker invocation above
- **Source URL** — `cap._source` (GitHub) and `cap._raw` (YAML)

Don't dump the full YAML unless asked — summarize and offer to expand.

## Caching

- The GitHub Contents listing per provider is cheap (~1 KB). Cache for the session.
- Capability YAMLs are small (1–5 KB). Cache aggressively.
- The full apis.io provider list (for cross-provider scans) comes from `discover-apis-io`.

## Failure modes

| Symptom | Likely cause |
|---|---|
| 404 from Contents API | Provider hasn't published `integrations/` yet — return empty list. |
| 403 with `rate limit exceeded` | Unauthenticated GitHub API quota (60/hour). Fall back to scraping the apis.io integrations page or pass a `GITHUB_TOKEN`. |
| YAML parse error | Bad capability — note the filename in your response. Continue with the rest. |