@installagent/sdk 0.1.0 → 0.2.0
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.
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +34 -9
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +25 -0
- package/dist/env-registry.js +69 -7
- package/dist/exec.js +15 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +14 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +40 -0
- package/dist/portal-admin.js +30 -0
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +47 -0
- package/dist/sync-repos.js +80 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +11 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/package.json +2 -2
- package/templates/env.example +33 -23
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
- package/templates/workspace-root/skills/CLAUDE.md +24 -6
- package/templates/workspace-root/skills/README.md +156 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: salesforce-api-snapshot
|
|
3
|
+
description: >-
|
|
4
|
+
Read data out of a client's Salesforce org (including managed-package orgs
|
|
5
|
+
like Lumary, Vlocity, nCino) and get it into something we build on — by
|
|
6
|
+
discovering the real object model with Tooling API SOQL instead of clicking
|
|
7
|
+
through Object Manager, then caching a scheduled read as a JSON snapshot in
|
|
8
|
+
GCS/S3 rather than querying Salesforce live from the app. Covers the four
|
|
9
|
+
things that waste a day each: the managed-package namespace trap (Object
|
|
10
|
+
Manager's search matches Labels, not API names, so it undercounts by 40x),
|
|
11
|
+
telling a real lookup from an external-ID text field (which is how you find
|
|
12
|
+
out the data you need isn't in Salesforce at all), the three-layer seam that
|
|
13
|
+
lets you build the entire pipeline against invented fixtures before you ever
|
|
14
|
+
hit a production org with no sandbox, and the least-privilege bucket wiring
|
|
15
|
+
between the n8n writer and the app reader. Use this WHENEVER an engagement
|
|
16
|
+
reads Salesforce (or any vendor CRM/EHR API) — "connect to their Salesforce",
|
|
17
|
+
"pull data from Lumary", "we need their CRM data in the dashboard", "what
|
|
18
|
+
objects do they have", "build the ingest", "cache the API response" — and
|
|
19
|
+
whenever a build has to run against a production org with no sandbox.
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
# Salesforce API → cached snapshot
|
|
23
|
+
|
|
24
|
+
The pattern behind Behavia Therapy's Geo Scheduling Map
|
|
25
|
+
(`clients/client-behaviatherapy/agent-scheduling-map/`): a scheduled read of a
|
|
26
|
+
managed-package Salesforce org, cached as a JSON snapshot in a bucket, served
|
|
27
|
+
to a gated Next.js app that never holds a Salesforce token.
|
|
28
|
+
|
|
29
|
+
Generalizes to any vendor system where you get read access to somebody's
|
|
30
|
+
production data and have to build something on top of it. The Salesforce
|
|
31
|
+
specifics are Parts 1 and 5; Parts 2–4 apply to any vendor API.
|
|
32
|
+
|
|
33
|
+
**Read the order carefully.** The build sequence here is deliberately
|
|
34
|
+
back-to-front — the Salesforce connection is the *last* thing you build, not
|
|
35
|
+
the first. That is the single most valuable idea in this document.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Part 0 — Confirm access is actually the access you need
|
|
40
|
+
|
|
41
|
+
Three facts to establish before scoping anything. Each has burned a day.
|
|
42
|
+
|
|
43
|
+
| Question | How to answer it | Why it matters |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| Which edition? | `SELECT Name, OrganizationType, InstanceName, IsSandbox FROM Organization` | **API access is included in Enterprise, Unlimited, and Performance.** Professional Edition needs a paid API add-on — if the client is on Professional, that's a purchase conversation, not a build task, and you want it on the table in week 1. |
|
|
46
|
+
| Is there a sandbox? | Same query — `IsSandbox` | If `false`, **there is no safe copy to develop against.** Every query you write runs against live production data. This changes the whole build order (Part 3). |
|
|
47
|
+
| Do we have System Admin, or a standard seat? | Setup → try to open Profiles / Permission Sets | **A standard seat cannot create a Connected App.** Discovering this at integration time costs a license purchase plus a client round-trip. Ask for the admin profile on the access checklist, at kickoff, in writing. |
|
|
48
|
+
|
|
49
|
+
Record all three in the engagement's `docs/04-access-checklist.md` row for the
|
|
50
|
+
system, with the date and who granted it. On Behavia: Enterprise Edition,
|
|
51
|
+
`IsSandbox = false`, System Admin granted 2026-08-04 after a prior finding that
|
|
52
|
+
the plain vendor "Admin" role couldn't reach Setup → Profiles.
|
|
53
|
+
|
|
54
|
+
**No sandbox changes your obligations.** Schema exploration becomes
|
|
55
|
+
reads-and-aggregates only — `COUNT()`, `GROUP BY`, metadata queries. Don't pull
|
|
56
|
+
data rows to "see what it looks like" when a `GROUP BY` answers the same
|
|
57
|
+
question, and don't iterate a half-working query against production. Both
|
|
58
|
+
rules fall out of Part 3 anyway.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Part 1 — Discover the real object model (Tooling API, not Object Manager)
|
|
63
|
+
|
|
64
|
+
### The namespace trap
|
|
65
|
+
|
|
66
|
+
Managed packages (Lumary, Vlocity, nCino, Veeva, …) prefix every object and
|
|
67
|
+
field with a namespace: `lmry__Session__c`, `lmry__Planned_Service__c`.
|
|
68
|
+
|
|
69
|
+
**Object Manager's search box matches the Label text, not the API name or the
|
|
70
|
+
namespace.** Searching the vendor's *product* name returns almost nothing. On
|
|
71
|
+
Behavia, searching "lumary" surfaced **6 objects out of 250+** — the real
|
|
72
|
+
prefix was `lmry`, and nothing about the UI tells you that. A technician who
|
|
73
|
+
trusts that search concludes the org is nearly empty and scopes the build on a
|
|
74
|
+
model that doesn't exist.
|
|
75
|
+
|
|
76
|
+
**Find the real prefix first:**
|
|
77
|
+
|
|
78
|
+
```sql
|
|
79
|
+
-- Tooling API. Groups every custom object by its namespace prefix.
|
|
80
|
+
SELECT NamespacePrefix, COUNT(Id)
|
|
81
|
+
FROM EntityDefinition
|
|
82
|
+
WHERE IsCustomizable = true
|
|
83
|
+
GROUP BY NamespacePrefix
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The prefix with hundreds of objects under it is the managed package. Use that
|
|
87
|
+
string, not the vendor's brand name, for everything below.
|
|
88
|
+
|
|
89
|
+
### Pull the model with SOQL, not clicks
|
|
90
|
+
|
|
91
|
+
Object Manager shows you one field at a time. `FieldDefinition` and
|
|
92
|
+
`EntityDefinition` give you the whole graph in a handful of queries you can
|
|
93
|
+
paste into a doc. Run them in **Developer Console → Query Editor with the
|
|
94
|
+
"Use Tooling API" checkbox ticked** (without it, these objects aren't
|
|
95
|
+
queryable and you get a confusing "sObject type is not supported" error).
|
|
96
|
+
|
|
97
|
+
The full copy-paste set, with what each one answers, is in
|
|
98
|
+
[`references/schema-discovery-soql.md`](references/schema-discovery-soql.md).
|
|
99
|
+
The four that matter most:
|
|
100
|
+
|
|
101
|
+
```sql
|
|
102
|
+
-- 1. Every object in the package, with field counts to spot the important ones.
|
|
103
|
+
SELECT QualifiedApiName, Label FROM EntityDefinition
|
|
104
|
+
WHERE QualifiedApiName LIKE 'ns__%' ORDER BY QualifiedApiName
|
|
105
|
+
|
|
106
|
+
-- 2. Every field on one object. FieldDefinition REQUIRES a single-object
|
|
107
|
+
-- filter — you cannot pull all fields for all objects in one query.
|
|
108
|
+
SELECT QualifiedApiName, Label, DataType FROM FieldDefinition
|
|
109
|
+
WHERE EntityDefinition.QualifiedApiName = 'ns__Session__c' ORDER BY QualifiedApiName
|
|
110
|
+
|
|
111
|
+
-- 3. RecordType census — tells you what the object is actually used for.
|
|
112
|
+
SELECT RecordType.Name, COUNT(Id) FROM Contact GROUP BY RecordType.Name
|
|
113
|
+
|
|
114
|
+
-- 4. Is a field a real relationship or just text? (see below)
|
|
115
|
+
SELECT QualifiedApiName, DataType FROM FieldDefinition
|
|
116
|
+
WHERE EntityDefinition.QualifiedApiName = 'ns__Planned_Service__c'
|
|
117
|
+
AND DataType LIKE 'Lookup%'
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Read `DataType` carefully — it's where the bad news lives
|
|
121
|
+
|
|
122
|
+
`FieldDefinition.DataType` renders as human-readable text, and the difference
|
|
123
|
+
between two values that look similar is the difference between a working build
|
|
124
|
+
and a scope change:
|
|
125
|
+
|
|
126
|
+
| `DataType` value | What it means | Consequence |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| `Lookup(Contact)` | A real relationship. | You can traverse it in SOQL. Safe to build on. |
|
|
129
|
+
| `Master-Detail(ns__Session__c)` | Real, and the child dies with the parent. | Same, plus cascade semantics. |
|
|
130
|
+
| `Text(255) (External ID)` | **Not a relationship.** A string another system writes. | The thing it names **lives in a different system entirely.** |
|
|
131
|
+
| `Formula(Text)` | Display-only, computed. | Often paired with an External ID field to make it *look* like a lookup in the UI. |
|
|
132
|
+
|
|
133
|
+
On Behavia this was the headline finding: `Planned_Service__c` (the
|
|
134
|
+
authorization-consumption record) had `Integration_Service_Agreement_Id__c` and
|
|
135
|
+
`_Name__c` — an External-ID text field plus a Formula display field. In the UI
|
|
136
|
+
it reads like a link to a Service Agreement. **There is no Service Agreement
|
|
137
|
+
object in that org.** A search across `EntityDefinition` for any
|
|
138
|
+
`%Agreement%`/`%Authoriz%` object confirmed it. The authorized-hours *ceiling*
|
|
139
|
+
— half the build's core metric — was never in Salesforce at all.
|
|
140
|
+
|
|
141
|
+
Finding that on day one of the spike is cheap. Finding it while wiring the
|
|
142
|
+
Connected App is a re-scope.
|
|
143
|
+
|
|
144
|
+
**When you find an External-ID field pointing at a system you can't name, try
|
|
145
|
+
to identify the system yourself before escalating to the client's SME.** In
|
|
146
|
+
rough order of how directly each names a vendor:
|
|
147
|
+
|
|
148
|
+
1. **Setup → Installed Packages** — a second managed package names the vendor outright.
|
|
149
|
+
2. **Setup → Named Credentials** and **Remote Site Settings** — every endpoint Salesforce is configured to call out to.
|
|
150
|
+
3. **Setup → Users** — integration/API-only users are usually named after the system they represent.
|
|
151
|
+
4. **Field Description / Help Text** on the External-ID field itself (Object Manager → object → Fields) — admins leave plain-English notes on exactly this kind of field.
|
|
152
|
+
5. `SELECT Id, LastModifiedBy.Name, LastModifiedBy.Profile.Name FROM ns__Object__c LIMIT 5` — whoever last wrote those fields is often the integration user.
|
|
153
|
+
|
|
154
|
+
Escalate only after those come up empty. Same rule as everywhere else: **don't
|
|
155
|
+
ask the client what our own data answers.**
|
|
156
|
+
|
|
157
|
+
### Write the findings down as a graph, not prose
|
|
158
|
+
|
|
159
|
+
Output of the spike is an indented relationship tree plus a numbered
|
|
160
|
+
findings list, ordered by *how much each one changes the build* — see
|
|
161
|
+
`clients/client-behaviatherapy/docs/14-scheduling-map-tech-spec.md` §3.4 for
|
|
162
|
+
the shape. Explicitly mark objects you saw referenced but never queried; a
|
|
163
|
+
half-explored graph that says so is useful, one that pretends to be complete
|
|
164
|
+
is a trap for the next technician.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Part 2 — Snapshot, don't query live
|
|
169
|
+
|
|
170
|
+
**Default to a scheduled read cached as a JSON snapshot.** Live per-request
|
|
171
|
+
querying should be an argued exception, not the starting point.
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
Salesforce (managed package)
|
|
175
|
+
│ Connected App, OAuth2 JWT bearer
|
|
176
|
+
▼
|
|
177
|
+
scheduled read (n8n, nightly + on-demand)
|
|
178
|
+
│
|
|
179
|
+
├─► derived-value cache (geocodes, enrichment — Part 6)
|
|
180
|
+
▼
|
|
181
|
+
JSON snapshot in a private bucket (GCS or S3)
|
|
182
|
+
▼
|
|
183
|
+
app reads the snapshot server-side, behind auth
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Four reasons, in the order they'll come up:
|
|
187
|
+
|
|
188
|
+
1. **Stability under a human decision.** Someone comparing options can't have
|
|
189
|
+
the data move underneath them mid-comparison.
|
|
190
|
+
2. **The browser never holds a vendor token.** The app reads a bucket; the
|
|
191
|
+
credential lives in n8n and nowhere else.
|
|
192
|
+
3. **Volume is almost always trivial.** A few hundred records is a small JSON
|
|
193
|
+
file. You are not saving anything real by streaming it live.
|
|
194
|
+
4. **API limits and cost are bounded and predictable** — one read per schedule
|
|
195
|
+
tick, not one per pageview per user.
|
|
196
|
+
|
|
197
|
+
Reach for live queries only when the client needs sub-minute freshness *and*
|
|
198
|
+
can articulate a decision that changes on that timescale. Write the reason in
|
|
199
|
+
the tech spec so the next person doesn't "optimize" the snapshot away.
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## Part 3 — The three-layer seam (build the whole thing before you connect)
|
|
204
|
+
|
|
205
|
+
**This is the part to copy verbatim.** With no sandbox, every exploratory query
|
|
206
|
+
runs against production. So: build and prove the *entire* pipeline against
|
|
207
|
+
invented fixtures shaped like the real object model, and let Salesforce be hit
|
|
208
|
+
only by a finished, working query.
|
|
209
|
+
|
|
210
|
+
Three modules, one seam:
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
lib/<vendor>/rawTypes.ts TypeScript shapes mirroring the REAL object graph
|
|
214
|
+
(from the Part 1 spike). Never changes at cutover.
|
|
215
|
+
lib/<vendor>/rawFixtures.ts Seeded-PRNG invented data emitting those shapes.
|
|
216
|
+
THE ONLY MODULE THE REAL INGEST REPLACES.
|
|
217
|
+
lib/<vendor>/normalize.ts raw shapes → the app's UI shapes.
|
|
218
|
+
Never changes at cutover.
|
|
219
|
+
|
|
220
|
+
lib/data.ts buildDataset() = normalize(buildRawFixtures())
|
|
221
|
+
← the one line that changes
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Why it works: `rawTypes.ts` is written from the schema spike, so the fixtures
|
|
225
|
+
are *fake data in the real shape*. Everything downstream — normalization,
|
|
226
|
+
scoring, UI, auth, deploy — is exercised against a faithful model. Cutover
|
|
227
|
+
swaps one function for a live query returning the same shape. Nothing else
|
|
228
|
+
moves.
|
|
229
|
+
|
|
230
|
+
Concretely, from the Behavia build (`.../web/lib/salesforce/`):
|
|
231
|
+
|
|
232
|
+
- `rawTypes.ts` models `RawContact` (with the `RecordType` split), `RawSession`
|
|
233
|
+
+ `RawClientAppointment`/`RawWorkerAppointment` (the parent/child appointment
|
|
234
|
+
model the spike found), `RawPlannedService`, and — crucially —
|
|
235
|
+
`RawAuthorizationCeiling` as a **separate external-system stand-in**, because
|
|
236
|
+
the spike proved that value isn't in Salesforce. Modeling the gap explicitly
|
|
237
|
+
means swapping its real source later touches nothing Salesforce-shaped.
|
|
238
|
+
- Each type carries a comment naming the real API name and the spec section it
|
|
239
|
+
came from. That's what makes the SOQL writable a month later.
|
|
240
|
+
- `data.ts` is deliberately a one-line composition, with a comment saying so.
|
|
241
|
+
|
|
242
|
+
**Build order that falls out of this:**
|
|
243
|
+
|
|
244
|
+
1. Schema spike (Part 1) → write `rawTypes.ts`.
|
|
245
|
+
2. Write `rawFixtures.ts`. Seeded PRNG, deterministic, and if you're porting an
|
|
246
|
+
existing prototype, keep the same seed so output is byte-identical to what
|
|
247
|
+
the client already reviewed.
|
|
248
|
+
3. Build the app, the auth gate, the deploy — all of it — on fixtures.
|
|
249
|
+
4. Build the ingest workflow (n8n), writing to the bucket, **still sourced from
|
|
250
|
+
fixtures**. Iterate here as much as you like; none of it touches the vendor.
|
|
251
|
+
5. Swap the app's read to the bucket. Verify end-to-end against the
|
|
252
|
+
fixture-sourced snapshot.
|
|
253
|
+
6. **Only now** create the Connected App and point the proven workflow at real
|
|
254
|
+
data. One run, confirm the snapshot lands, done.
|
|
255
|
+
|
|
256
|
+
Keep an `INVENTED DATA` badge visible in any UI running on fixtures, and make
|
|
257
|
+
removing it part of the cutover checklist.
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Part 4 — Where the snapshot lives
|
|
262
|
+
|
|
263
|
+
**Pick the bucket by whose compliance envelope you need**, not by preference:
|
|
264
|
+
|
|
265
|
+
- **The client's own cloud project** when the data is regulated and the client
|
|
266
|
+
has (or can accept) the provider's BAA/DPA. On Behavia, the client's authorized
|
|
267
|
+
signer accepted
|
|
268
|
+
Google's Cloud Data Processing Addendum *and* the GCP HIPAA BAA on Behavia's
|
|
269
|
+
own project, which is what made GCS a legitimate place for the snapshot.
|
|
270
|
+
- **Our AWS account** for non-regulated vendor data — the same account the
|
|
271
|
+
SFTP drop lives in (see the `vendor-feed-ingestion` skill).
|
|
272
|
+
|
|
273
|
+
> A cloud provider's BAA covers *the provider*. It says nothing about whether
|
|
274
|
+
> **we** are authorized to process the data. Those are two separate agreements
|
|
275
|
+
> and two separate rows on the access checklist. Don't let one be quoted as
|
|
276
|
+
> clearing the other.
|
|
277
|
+
|
|
278
|
+
**Two service accounts, least privilege, always:**
|
|
279
|
+
|
|
280
|
+
| Identity | Role | Where the key lives |
|
|
281
|
+
|---|---|---|
|
|
282
|
+
| ingest writer (n8n) | GCS `roles/storage.objectCreator` · S3 `s3:PutObject` on the one prefix | the client's 1Password vault → n8n credential |
|
|
283
|
+
| app reader (Vercel) | GCS `roles/storage.objectViewer` · S3 `s3:GetObject` on the one prefix | Vercel project env var, **server-side only** |
|
|
284
|
+
|
|
285
|
+
Bucket private, no public access, versioned (free rollback when a bad ingest
|
|
286
|
+
overwrites a good snapshot). Neither key ever enters git — the repo gets
|
|
287
|
+
placeholder names in `.env.example` and a pointer to the vault.
|
|
288
|
+
|
|
289
|
+
The app reads the snapshot **inside a server route that already checks the
|
|
290
|
+
session** — never from client-side code, never with the reader key exposed to
|
|
291
|
+
the browser. See the `sso-gated-client-app` skill for that route's shape.
|
|
292
|
+
|
|
293
|
+
Full bucket/IAM/env wiring, both clouds:
|
|
294
|
+
[`references/snapshot-storage.md`](references/snapshot-storage.md).
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## Part 5 — The Connected App (last, not first)
|
|
299
|
+
|
|
300
|
+
Only after Parts 3 and 4 are proven:
|
|
301
|
+
|
|
302
|
+
1. **Setup → App Manager → New Connected App**, OAuth enabled.
|
|
303
|
+
2. **JWT bearer flow** — a server-to-server integration, no interactive login,
|
|
304
|
+
no refresh-token expiry to babysit. Generate a keypair, upload the cert,
|
|
305
|
+
note the Consumer Key.
|
|
306
|
+
3. **Scopes:** `api` and `refresh_token, offline_access`. Nothing wider.
|
|
307
|
+
4. **Pre-authorize the integration user** — the JWT flow fails unless the
|
|
308
|
+
running user is permitted on the Connected App (Manage Profiles /
|
|
309
|
+
Permission Sets). This is the most common "it worked in Postman, not in
|
|
310
|
+
n8n" cause.
|
|
311
|
+
5. **Read-only by construction.** The integration user's profile should have no
|
|
312
|
+
write permission on the objects you touch. Belt-and-braces on top of a
|
|
313
|
+
read-only workflow — someone will edit that workflow later.
|
|
314
|
+
6. Private key into the client's 1Password vault, then into the n8n credential.
|
|
315
|
+
Never into the repo, never pasted into chat.
|
|
316
|
+
|
|
317
|
+
Then run the query once, confirm the snapshot, and stop. On a no-sandbox org
|
|
318
|
+
every run is a production run.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## Part 6 — Cache derived values too, and treat precision as a privacy setting
|
|
323
|
+
|
|
324
|
+
Anything you compute *from* the vendor data — geocodes, enrichment lookups,
|
|
325
|
+
LLM-generated summaries — gets its own cache, keyed on the input.
|
|
326
|
+
|
|
327
|
+
**Geocoding, the canonical case:**
|
|
328
|
+
|
|
329
|
+
- **Never geocode on page load.** Resolve each address once, store the
|
|
330
|
+
coordinate, re-resolve only when the address string changes. Addresses barely
|
|
331
|
+
change; the API bills per call; and every address that crosses the network is
|
|
332
|
+
an exposure.
|
|
333
|
+
- **Round coordinates before storage — a privacy decision, not a rendering
|
|
334
|
+
one.** A full-precision pin on a home address *is* the family's front door.
|
|
335
|
+
~3 decimal places ≈ 110 m. Round in the ingest, so full precision never
|
|
336
|
+
reaches the snapshot, let alone the browser.
|
|
337
|
+
- **Check whether the vendor already geocoded it.** Behavia's `Session__c`
|
|
338
|
+
carries its own `Geolocation__c` and a full address block; if populated,
|
|
339
|
+
the geocoding step disappears. Verify it actually holds data before
|
|
340
|
+
de-scoping — a field existing is not a field being used.
|
|
341
|
+
|
|
342
|
+
**Minimize the snapshot to what the screen needs.** First name plus initial,
|
|
343
|
+
not full names. Rounded coordinates, not addresses. An age integer, not a DOB.
|
|
344
|
+
No payer IDs. The snapshot is the blast radius — anything in it is one auth
|
|
345
|
+
bug away from being public.
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## Requirements checklist
|
|
350
|
+
|
|
351
|
+
- [ ] Edition, `IsSandbox`, and admin-profile status confirmed by query and recorded on the access checklist
|
|
352
|
+
- [ ] Real namespace prefix found via `EntityDefinition GROUP BY NamespacePrefix` (not the vendor's brand name)
|
|
353
|
+
- [ ] Object graph pulled via Tooling API SOQL and written up as a relationship tree + findings ordered by build impact
|
|
354
|
+
- [ ] Every field the build depends on classified: real lookup vs External-ID text
|
|
355
|
+
- [ ] Any External-ID field traced to its owning system (or escalated after the five self-service checks)
|
|
356
|
+
- [ ] `rawTypes.ts` / `rawFixtures.ts` / `normalize.ts` split in place, with the one-line seam in `data.ts`
|
|
357
|
+
- [ ] Entire pipeline proven on fixtures — app, auth, deploy, and ingest — before the Connected App exists
|
|
358
|
+
- [ ] Private bucket in the right compliance envelope; two least-privilege service accounts; versioning on
|
|
359
|
+
- [ ] Connected App uses JWT bearer, minimum scopes, a pre-authorized read-only integration user
|
|
360
|
+
- [ ] Derived values cached; coordinates rounded in the ingest
|
|
361
|
+
- [ ] Snapshot minimized to what the screen renders
|
|
362
|
+
- [ ] `INVENTED DATA` badge removed only as part of the cutover, and the delivery log updated
|
|
363
|
+
|
|
364
|
+
## Known gaps to flag, not silently skip
|
|
365
|
+
|
|
366
|
+
- **A schema spike is a point-in-time read.** Managed packages get upgraded and
|
|
367
|
+
admins add fields. Date the write-up and re-run the field queries before
|
|
368
|
+
trusting it months later.
|
|
369
|
+
- **`FieldDefinition` won't tell you whether a field is *populated*.** It
|
|
370
|
+
describes the model, not the data. A `COUNT()` with a `!= null` filter is a
|
|
371
|
+
separate question, and on a no-sandbox org it's a production query — decide
|
|
372
|
+
deliberately whether it's worth one.
|
|
373
|
+
- **Aggregate queries still hit real data.** `GROUP BY` and `COUNT()` are far
|
|
374
|
+
lower-risk than pulling rows, but "read-only" is not the same as "no data
|
|
375
|
+
was accessed." Say which you did in the delivery log.
|
|
376
|
+
- **This skill covers reads.** Writing back to Salesforce is a different risk
|
|
377
|
+
profile entirely — duplicate rules, validation rules, triggers, and workflow
|
|
378
|
+
automations fire on our writes. Don't extrapolate this pattern to a write
|
|
379
|
+
integration without a separate spec.
|
package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Schema-discovery SOQL — copy-paste set
|
|
2
|
+
|
|
3
|
+
Run these in **Developer Console → Query Editor** with the **"Use Tooling API"**
|
|
4
|
+
checkbox ticked (bottom of the panel). Without it, `EntityDefinition` and
|
|
5
|
+
`FieldDefinition` return `sObject type 'EntityDefinition' is not supported`.
|
|
6
|
+
|
|
7
|
+
Replace `ns__` with the real namespace prefix from query 2 — **not** the
|
|
8
|
+
vendor's brand name.
|
|
9
|
+
|
|
10
|
+
Everything here is metadata or an aggregate. No data rows leave the org.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. Org facts — run this first, always
|
|
15
|
+
|
|
16
|
+
```sql
|
|
17
|
+
SELECT Name, OrganizationType, InstanceName, IsSandbox FROM Organization
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- `OrganizationType` — `Enterprise Edition` / `Unlimited Edition` /
|
|
21
|
+
`Performance Edition` include API access. `Professional Edition` does not
|
|
22
|
+
without a paid add-on.
|
|
23
|
+
- `IsSandbox = false` means every subsequent query is a production query.
|
|
24
|
+
|
|
25
|
+
## 2. Find the real namespace prefix
|
|
26
|
+
|
|
27
|
+
```sql
|
|
28
|
+
SELECT NamespacePrefix, COUNT(Id)
|
|
29
|
+
FROM EntityDefinition
|
|
30
|
+
WHERE IsCustomizable = true
|
|
31
|
+
GROUP BY NamespacePrefix
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The prefix with hundreds of objects is the managed package. Object Manager's
|
|
35
|
+
search box matches **Label** text only, so searching the vendor's product name
|
|
36
|
+
will badly undercount — this query is the reliable route.
|
|
37
|
+
|
|
38
|
+
## 3. Every object in the package
|
|
39
|
+
|
|
40
|
+
```sql
|
|
41
|
+
SELECT QualifiedApiName, Label, IsCustomSetting
|
|
42
|
+
FROM EntityDefinition
|
|
43
|
+
WHERE QualifiedApiName LIKE 'ns__%'
|
|
44
|
+
ORDER BY QualifiedApiName
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Scan the labels for the nouns in the client's own vocabulary (Session, Visit,
|
|
48
|
+
Authorization, Shift). Objects whose label matches a word the client uses on
|
|
49
|
+
calls are your candidate set.
|
|
50
|
+
|
|
51
|
+
## 4. Every field on one object
|
|
52
|
+
|
|
53
|
+
`FieldDefinition` **requires** a filter on a single
|
|
54
|
+
`EntityDefinition.QualifiedApiName`. You cannot pull all fields for all objects
|
|
55
|
+
in one query — loop it per candidate object.
|
|
56
|
+
|
|
57
|
+
```sql
|
|
58
|
+
SELECT QualifiedApiName, Label, DataType, IsCalculated, IsNillable
|
|
59
|
+
FROM FieldDefinition
|
|
60
|
+
WHERE EntityDefinition.QualifiedApiName = 'ns__Session__c'
|
|
61
|
+
ORDER BY QualifiedApiName
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`DataType` renders human-readable and inlines the relationship target:
|
|
65
|
+
|
|
66
|
+
| Value | Meaning |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `Lookup(Contact)` | Real relationship — traversable in SOQL |
|
|
69
|
+
| `Master-Detail(ns__Session__c)` | Real, cascade-deletes with parent |
|
|
70
|
+
| `Text(255) (External ID)` | **Not** a relationship — a string written by another system |
|
|
71
|
+
| `Formula(Text)` | Display-only; frequently paired with an External ID to mimic a lookup |
|
|
72
|
+
| `Picklist` | Get the values from query 8 before assuming a vocabulary |
|
|
73
|
+
|
|
74
|
+
## 5. Just the relationships, to draw the graph
|
|
75
|
+
|
|
76
|
+
```sql
|
|
77
|
+
SELECT QualifiedApiName, Label, DataType
|
|
78
|
+
FROM FieldDefinition
|
|
79
|
+
WHERE EntityDefinition.QualifiedApiName = 'ns__Session__c'
|
|
80
|
+
AND (DataType LIKE 'Lookup%' OR DataType LIKE 'Master-Detail%')
|
|
81
|
+
ORDER BY QualifiedApiName
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Run per object, then assemble into an indented tree. Mark every object you see
|
|
85
|
+
referenced but haven't queried yet — an honest partial graph beats a
|
|
86
|
+
confident-looking complete-seeming one.
|
|
87
|
+
|
|
88
|
+
## 6. Does the object you need even exist?
|
|
89
|
+
|
|
90
|
+
```sql
|
|
91
|
+
SELECT QualifiedApiName, Label FROM EntityDefinition
|
|
92
|
+
WHERE QualifiedApiName LIKE '%Authoriz%'
|
|
93
|
+
OR QualifiedApiName LIKE '%Agreement%'
|
|
94
|
+
OR Label LIKE '%Authorization%'
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Search both API name and Label, and search for the *concept* rather than one
|
|
98
|
+
spelling. A null result here is a real finding: the data lives in another
|
|
99
|
+
system. Say so in the spec and go look for that system (SKILL.md Part 1).
|
|
100
|
+
|
|
101
|
+
## 7. RecordType census — what an object is actually used for
|
|
102
|
+
|
|
103
|
+
```sql
|
|
104
|
+
SELECT RecordType.Name, COUNT(Id) FROM Contact GROUP BY RecordType.Name
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Standard SOQL (untick Tooling API for this one). On Behavia: Employee 90 /
|
|
108
|
+
Client 157 / **Other 268** — the biggest bucket was undefined, and no
|
|
109
|
+
"active client" filter could be written honestly until someone named it.
|
|
110
|
+
|
|
111
|
+
**Always run the census before writing a filter on RecordType.** If a bucket
|
|
112
|
+
you can't explain is large, that's a question for the client's SME, not an
|
|
113
|
+
assumption.
|
|
114
|
+
|
|
115
|
+
## 8. Picklist values (the vocabulary trap)
|
|
116
|
+
|
|
117
|
+
```sql
|
|
118
|
+
SELECT Value, Label, IsActive
|
|
119
|
+
FROM PicklistValueInfo
|
|
120
|
+
WHERE EntityParticleId = 'ns__Session__c.ns__Visit_Type__c'
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Never assume a status vocabulary. On CarVision, a config file assumed a
|
|
124
|
+
`Engaged / Visit / Proposal` funnel; the live feed emitted `Open / Dead /
|
|
125
|
+
Delivered`. Same class of mistake, different vendor — check the real values
|
|
126
|
+
before encoding rules against them.
|
|
127
|
+
|
|
128
|
+
## 9. Who writes the mystery integration fields
|
|
129
|
+
|
|
130
|
+
```sql
|
|
131
|
+
SELECT Id, LastModifiedBy.Name, LastModifiedBy.Profile.Name
|
|
132
|
+
FROM ns__Planned_Service__c LIMIT 5
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Standard SOQL, and it *does* touch data rows — use it only when steps 1–4 of
|
|
136
|
+
the SKILL.md self-service list came up empty, and keep the `LIMIT` small.
|
|
137
|
+
Integration users are usually named after the system they represent.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Writing up the results
|
|
142
|
+
|
|
143
|
+
Two artifacts, both in the client build repo's `docs/`:
|
|
144
|
+
|
|
145
|
+
1. **The tech spec section** — indented relationship tree, then numbered
|
|
146
|
+
findings *ordered by how much each changes the build*. Mark every unexplored
|
|
147
|
+
object explicitly.
|
|
148
|
+
2. **A delivery-log entry** — dated, with "Where it runs: n/a — read-only
|
|
149
|
+
schema queries, no data rows pulled" so the compliance posture of the spike
|
|
150
|
+
is on the record.
|
|
151
|
+
|
|
152
|
+
Exemplar: `clients/client-behaviatherapy/docs/14-scheduling-map-tech-spec.md`
|
|
153
|
+
§3.4 and the 2026-08-05 entry in that repo's `docs/00-delivery-log.md`.
|
package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Snapshot storage — bucket, IAM, and the two-key wiring
|
|
2
|
+
|
|
3
|
+
The cached-snapshot half of the pattern, in both clouds. The rule that matters
|
|
4
|
+
more than either: **two identities, one write, one read, neither in git.**
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Choosing the cloud
|
|
9
|
+
|
|
10
|
+
| Situation | Put the snapshot in | Why |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| Regulated data (PHI, financial records) | **The client's own cloud project** | The client can accept the provider's BAA/DPA on their own project. We can't accept it on their behalf. |
|
|
13
|
+
| Client already has a project for this workload | **Theirs** | One less provisioning step and one less billing conversation — on Behavia, the client volunteered an existing GCP project with Places API already enabled. |
|
|
14
|
+
| Ordinary vendor/business data | **Our AWS account** (`installagent` profile) | Same account as the shared SFTP drop; one place to audit. |
|
|
15
|
+
|
|
16
|
+
> **A provider BAA is not our authorization.** Google/AWS signing a BAA covers
|
|
17
|
+
> *them* processing the data. Whether **Install Agent** may process it is a
|
|
18
|
+
> separate agreement with the client. Two rows on
|
|
19
|
+
> `docs/04-access-checklist.md`, tracked separately, and neither one clears the
|
|
20
|
+
> other. If a build proceeds before the client-side agreement is signed, that
|
|
21
|
+
> needs an explicit, written, scoped decision doc — not a verbal "go ahead"
|
|
22
|
+
> remembered differently by two people later.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## GCS (client's project)
|
|
27
|
+
|
|
28
|
+
**Bucket:** uniform bucket-level access, public access prevention **enforced**,
|
|
29
|
+
object versioning **on**, single region, a lifecycle rule expiring old versions
|
|
30
|
+
after ~30 days.
|
|
31
|
+
|
|
32
|
+
**Two service accounts:**
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# writer — the n8n ingest
|
|
36
|
+
gcloud iam service-accounts create ingest-writer --project "$PROJECT"
|
|
37
|
+
gcloud storage buckets add-iam-policy-binding "gs://$BUCKET" \
|
|
38
|
+
--member="serviceAccount:ingest-writer@$PROJECT.iam.gserviceaccount.com" \
|
|
39
|
+
--role="roles/storage.objectCreator"
|
|
40
|
+
|
|
41
|
+
# reader — the app
|
|
42
|
+
gcloud iam service-accounts create app-reader --project "$PROJECT"
|
|
43
|
+
gcloud storage buckets add-iam-policy-binding "gs://$BUCKET" \
|
|
44
|
+
--member="serviceAccount:app-reader@$PROJECT.iam.gserviceaccount.com" \
|
|
45
|
+
--role="roles/storage.objectViewer"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`objectCreator` can write but **cannot read or list** — a compromised ingest
|
|
49
|
+
credential can't exfiltrate the history. `objectViewer` can read but cannot
|
|
50
|
+
write. Neither can delete. Don't collapse them into one `objectAdmin` "for
|
|
51
|
+
now"; that "for now" is permanent.
|
|
52
|
+
|
|
53
|
+
Key JSON → the client's 1Password vault → n8n credential (writer) and the
|
|
54
|
+
Vercel project env (reader). Nowhere else.
|
|
55
|
+
|
|
56
|
+
## S3 (our account)
|
|
57
|
+
|
|
58
|
+
**Bucket:** Block Public Access on all four settings, SSE enabled, versioning
|
|
59
|
+
on, a bucket policy denying non-TLS requests, `RETAIN` on stack delete.
|
|
60
|
+
|
|
61
|
+
Two IAM roles/users scoped to a **single prefix** each:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"Effect": "Allow",
|
|
66
|
+
"Action": ["s3:PutObject"],
|
|
67
|
+
"Resource": "arn:aws:s3:::installagent-<purpose>/<client>/<source>/*"
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
…and the reader with `s3:GetObject` on the same prefix. Prefer an instance/task
|
|
72
|
+
role over long-lived access keys wherever the consumer runs in AWS — the SFTP
|
|
73
|
+
host reaches S3 by instance role precisely so no keys sit on the box.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## The read path in the app
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
// app/api/<thing>/route.ts — server-side only
|
|
81
|
+
export async function GET() {
|
|
82
|
+
const session = await auth();
|
|
83
|
+
if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
|
84
|
+
|
|
85
|
+
const snapshot = await fetchSnapshot(); // reader credential, server env only
|
|
86
|
+
return NextResponse.json(snapshot);
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Non-negotiables:
|
|
91
|
+
|
|
92
|
+
- The reader credential is a **server-side** env var. Never `NEXT_PUBLIC_*`.
|
|
93
|
+
- The route checks the session **itself**. Middleware/proxy protection is a
|
|
94
|
+
second layer, not the layer — see the `sso-gated-client-app` skill.
|
|
95
|
+
- The snapshot is never bundled into the page or embedded in HTML; it's
|
|
96
|
+
fetched by the gated route.
|
|
97
|
+
- **Access logging on this route** — who fetched the snapshot, when. Cheap to
|
|
98
|
+
add at build time, awkward to retrofit after an incident question.
|
|
99
|
+
|
|
100
|
+
## Freshness and failure
|
|
101
|
+
|
|
102
|
+
- **Write the produced-at timestamp into the snapshot** and surface it in the
|
|
103
|
+
UI. A silently stale screen is worse than an obviously broken one — a user
|
|
104
|
+
can't tell that what they're looking at is two days old unless you tell them.
|
|
105
|
+
- **Write atomically.** Upload to a temp key and copy/rename into place, so a
|
|
106
|
+
reader never sees a half-written file. Same discipline as the SFTP
|
|
107
|
+
`put .part` → `rename` contract in the `vendor-feed-ingestion` skill.
|
|
108
|
+
- **Don't overwrite good data with a bad run.** If the ingest produced
|
|
109
|
+
obviously degraded output, fail loudly and leave yesterday's snapshot in
|
|
110
|
+
place. Versioning is the backstop, guards are the mechanism — the
|
|
111
|
+
`vendor-feed-ingestion` skill covers how to calibrate them.
|
|
112
|
+
|
|
113
|
+
## Env-var summary
|
|
114
|
+
|
|
115
|
+
| Var | Where | Never |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| `SNAPSHOT_BUCKET` | app server env + n8n | — |
|
|
118
|
+
| `SNAPSHOT_READER_KEY` (or role) | app server env, from 1Password | prefixed `NEXT_PUBLIC_` |
|
|
119
|
+
| ingest writer key | n8n credential, from 1Password | in the repo, in a workflow JSON export, in Slack |
|
|
120
|
+
|
|
121
|
+
`.env.example` carries the **names** with placeholder values and a comment
|
|
122
|
+
pointing at the client's 1Password vault. Real values never land in git.
|