@drawbridge/drawbridge-agents 0.1.39 → 0.1.40
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: drawbridge-add-connection
|
|
3
|
+
description: Use when adding a new vendor connection (a new manifest in drawbridge-utils) — runs the auth-type assessment FIRST so the integration is built the way the vendor's own docs recommend, then walks the build against the documented checklist and its guards.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Add a connection
|
|
7
|
+
|
|
8
|
+
A connection is one manifest file in `drawbridge-utils/lib/connections/`, and the
|
|
9
|
+
build half is documented — `drawbridge-docs/reference/connection-hooks.md`,
|
|
10
|
+
"Adding a connection". This skill exists for what comes BEFORE the file: deciding
|
|
11
|
+
what kind of connection to build, from the vendor's documentation rather than
|
|
12
|
+
from whichever auth mechanism is easiest to wire.
|
|
13
|
+
|
|
14
|
+
The failure it prevents is real: Attentive was first built as pasted API keys
|
|
15
|
+
because keys worked, and their docs turned out to frame private-app keys as
|
|
16
|
+
"integrate your own account" — the public OAuth app was the documented path for
|
|
17
|
+
platforms like Drawbridge. The rebuild cost an afternoon; the assessment costs
|
|
18
|
+
ten minutes.
|
|
19
|
+
|
|
20
|
+
## When to use
|
|
21
|
+
|
|
22
|
+
Any new vendor manifest, and any auth-type change to an existing one (keys →
|
|
23
|
+
OAuth is a rebuild of the auth surface, not a tweak).
|
|
24
|
+
|
|
25
|
+
## Steps
|
|
26
|
+
|
|
27
|
+
1. **Fetch the vendor's developer docs and answer these in writing, with the
|
|
28
|
+
URL of the page that answers each.** Never from memory — the Klaviyo consent
|
|
29
|
+
url was once written from memory, pointed at their API host, and stalled
|
|
30
|
+
every merchant on a blank page.
|
|
31
|
+
|
|
32
|
+
- What auth mechanisms exist, and **who does the vendor say each is for**?
|
|
33
|
+
The distinction that matters is *your own account* versus *accounts outside
|
|
34
|
+
your organization*. Drawbridge is always the second: merchants connect
|
|
35
|
+
THEIR account to OUR platform.
|
|
36
|
+
- Is there a partner / public-app / marketplace program? What does
|
|
37
|
+
registration take, and what credentials does it issue?
|
|
38
|
+
- For OAuth: authorize url, token url, how client credentials are sent
|
|
39
|
+
(form fields vs Basic header), whether PKCE is required, token lifetime,
|
|
40
|
+
whether refresh tokens exist, scope names.
|
|
41
|
+
|
|
42
|
+
2. **Pick the `auth.type` from the answers, not from convenience:**
|
|
43
|
+
|
|
44
|
+
| vendor's shape | type |
|
|
45
|
+
|---|---|
|
|
46
|
+
| installed from the vendor's app store, never redirects back | `install` |
|
|
47
|
+
| registered app, merchant consents on the vendor's screen | `oauth` |
|
|
48
|
+
| the vendor offers ONLY per-account credentials | `keys` |
|
|
49
|
+
| no third party behind it at all | `generated` |
|
|
50
|
+
|
|
51
|
+
`keys` when OAuth exists is a decision someone must make out loud — usually
|
|
52
|
+
as an explicitly-flagged interim while a partner registration is pending, and
|
|
53
|
+
the manifest header says so.
|
|
54
|
+
|
|
55
|
+
3. **If the app is not yet registered, build it dormant.** `requires` names the
|
|
56
|
+
client env vars that will exist after registration; until they land on a
|
|
57
|
+
deployment, the connection is offered nowhere. Shipping the manifest complete
|
|
58
|
+
and inert beats waiting — adding the env vars becomes the launch.
|
|
59
|
+
|
|
60
|
+
4. **Record the assessment in the manifest header**: every cited fact, every
|
|
61
|
+
contradiction between the vendor's own pages (cite both and say which one the
|
|
62
|
+
code models), and — for OAuth — the questions only a live registration
|
|
63
|
+
answers: does consent echo `state` back, what is the real token lifetime,
|
|
64
|
+
does one app accept both environments' redirect urls.
|
|
65
|
+
|
|
66
|
+
5. **Build against the checklist** in
|
|
67
|
+
`drawbridge-docs/reference/connection-hooks.md` → "Adding a connection". Its
|
|
68
|
+
guards are the enforcement: the directory-registration test, the
|
|
69
|
+
feature-grant test, `build()` itself. Trust the named failures over your
|
|
70
|
+
memory of the steps.
|
|
71
|
+
|
|
72
|
+
## Notes
|
|
73
|
+
|
|
74
|
+
- The manifest is the only place vendor facts live. If the assessment finds a
|
|
75
|
+
fact that must hold across repos, record it with `drawbridge-record-contract`.
|
|
76
|
+
- The picker/search question is part of the assessment: if the vendor's list
|
|
77
|
+
endpoint filters by name server-side, the field must NOT declare
|
|
78
|
+
`search : false` — Attentive was the first vendor that could, and a test pins
|
|
79
|
+
that it stays searchable.
|
package/package.json
CHANGED