[seanspeaks]

Summary

Adds @friggframework/api-module-trello at packages/v1-ready/trello/ — a Frigg v2 API module for Trello’s REST API (members, boards, lists, cards, organizations/workspaces, labels, webhooks).

No prior Trello package existed under packages/ (including needs-updating); this is a greenfield module shaped like packages/v1-ready/fathom/, with webhook extensions following packages/v1-ready/hubspot/extensions/webhooks/ (and Front’s sibling pattern).

What the API is & sources

Trello (Atlassian) project boards. Official docs only:

• Official OpenAPI (source of truth for this module’s contract) — https://developer.atlassian.com/cloud/trello/swagger.v3.json
• REST API — https://developer.atlassian.com/cloud/trello/rest/
• Authorization — https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/
• Webhooks — https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/
• Object definitions — https://developer.atlassian.com/cloud/trello/guides/rest-api/object-definitions/
• Power-Ups — https://developer.atlassian.com/cloud/trello/power-ups/

Curated contract: trello.openapi.yaml — subset of the official swagger (same server URL, security schemes, paths/methods/params/schemas for the scoped ops; camelCase operationIds for the Api client).

Spec recheck (follow-up)

Diffed every curated operation against swagger.v3.json and fixed conflicts:

Area	Was (incorrect vs vendor)	Now
Security schemes	Invented ApiKeyAndToken header Authorization	Official APIKey (key query) + APIToken (token query); global security: [{APIKey:[], APIToken:[]}]
Client auth	Sent OAuth-style Authorization header	Injects key + token query params to match OpenAPI schemes
POST/PUT /webhooks, POST /tokens/{token}/webhooks	requestBody JSON	Official query params (callbackURL, idModel, …)
POST /labels	Only idBoard required	Official required: name, color, idBoard
Organization schema	Included non-schema desc	Fields from official Organization only
Webhook schema	Missing firstConsecutiveFailDate	Matches official Webhook
List schema	Generic “List”	Official TrelloList properties
Color	Free string	Official Color enum
Card due/start formats	date-time	Official date
Param catalogs	Partial / invented shapes	Regenerated from vendor parameters for each scoped op

Unchanged scope: still the same 24 operations (identity, boards/lists/cards CRUD, orgs, labels, webhooks). Optional query params now mirror the vendor lists for those ops; no new endpoints.

Auth method

API key + user token (Trello Auth / Power-Up key), matching official OpenAPI APIKey + APIToken.

• Key from https://trello.com/apps/admin → Trello Auth
• Token via https://trello.com/1/authorize?expiration=never&scope=read,write,account&response_type=token&key=…
• Client sends ?key=&token= on every request
• Definition uses setAuthParams + getAuthorizationRequirements (apiKey form); identity from GET /members/me
• Env: TRELLO_API_KEY, TRELLO_TOKEN, TRELLO_API_SECRET (webhook HMAC)

No partner approval required for classic key+token REST access. The full vendor swagger marks many operations with operation-level OAuth2 security (overriding global key+token); the Authorization and Webhooks guides still document classic key+token for these routes — we keep key+token and declare global OpenAPI security as the vendor document’s global schemes.

Endpoints covered

Method	HTTP
getMember	GET /members/{id}
listBoards	GET /members/{id}/boards
getBoard / createBoard / updateBoard	boards
listLists / getList / createList / updateList	lists
listCards / listListCards / getCard / createCard / updateCard	cards
listOrganizations / getOrganization	organizations
listLabels / createLabel	labels
createWebhook / getWebhook / updateWebhook / deleteWebhook	/webhooks
listTokenWebhooks / createTokenWebhook	/tokens/{token}/webhooks
verifyWebhookSignature	local helper (X-Trello-Webhook)

Endpoints skipped (intentionally)

The official OpenAPI has ~261 operations. Skipped for this core integration surface:

• Actions, attachments, checklists/checkItems, custom fields, stickers, board plugins/exports, enterprises, search, notifications, emoji, batch
• Atlassian OAuth 2.0 (3LO) as the module’s auth path — schemes/scopes are present in trello.openapi.yaml components for reference (OAuth2), but the Definition/Api use classic key+token

Capability manifest & Fenestra

• trello.capabilities.json — capability-manifest/v0.1; fields aligned to official schemas (org without invented desc; webhook firstConsecutiveFailDate; label.create requires name+color+idBoard).
• trello.fenestra.yaml — draft Power-Ups UI ecosystem; fenestra validate ✓.
• extensions/webhooks/ — Tier-3 DB-free receiver; prefer ?memberId=<externalId> on callbackURL.

Commands run & output

npm test (module)

PASS tests/api.test.js
PASS tests/definition.test.js
PASS tests/spec-sync.test.js

Test Suites: 3 passed, 3 total
Tests:       34 passed, 34 total

Artifact: npm test output

frigg validate --module

  ✓ The module definition is valid.
  schema.valid: true
  structural issues: 0

(via frigg PR #702 validators.) Artifact: frigg validate output

frigg auth test .

Pending credentials — no sandbox API key/token available; not faked.

Fenestra validate

✓ Valid Fenestra document
  Contains: 3 extension points, 1 SDKs

Artifact: fenestra validate output

Open questions

1. Prefer Atlassian OAuth 2.0 (3LO) over classic key+token? Partially answered by spec: vendor OpenAPI global security is APIKey+APIToken; many ops also list operation-level OAuth2 with scopes (read:board:trello, etc.). Classic key+token remains correct for this module; OAuth2 wiring is a product choice for a follow-up, not a swagger conflict for key+token clients.
2. Webhook tenant resolve: Trello payloads do not carry a stable account id. We document ?memberId= on callbackURL. Is that the preferred Frigg convention?
3. lefthookhq/lefthook-bots definitions/manifests/ was not accessible (404); no draft manifest available.
4. Any Atlassian partner/marketplace gates beyond Power-Up key generation for Left Hook’s listing?
5. Whether to expand the curated OpenAPI to checklists, attachments, and comments in a follow-up.

Credit

• Module shape / tests / OpenAPI sync pattern: packages/v1-ready/fathom/
• Webhook extension pattern: packages/v1-ready/hubspot/extensions/webhooks/ (+ Front sibling)
• Capability / Fenestra patterns: recent sibling modules (Notion, Front, Box PRs)
• Official Trello OpenAPI + docs (Atlassian) — contract regenerated from swagger.v3.json on recheck

_{To show artifacts inline, enable in settings.}