@particle-academy/hubspot-js 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ The four packages share one version, because they are generated from one
 `provider/` definition and a version that meant something different in each
 would be a version nobody could reason about.
 
+## [0.3.0] — 2026-08-24
+
+### Added
+
+- **The README now says how to SET THIS CONNECTOR UP**, in the package itself.
+
+Until now it explained what the four packages are, what they cost and why the
+repo is generated — and said nothing about credentials, scopes, sandboxes or
+operations. Somebody who installed it could not learn from it which credentials
+a connection needs, where a human GETS them, which scopes to request, or what
+the connector can actually do. All of that was already in the definition; the
+one document a consumer reads was the one that omitted everything actionable.
+
+The new **Setting it up** section carries:
+
+- every credential, with the text saying where the value comes from, whether it
+  is **per installation** or **per connected account**, and whether it is secret;
+- the OAuth authorize and token URLs and the exact scopes, verbatim;
+- the access-token lifetime, and where refresh tokens ROTATE, the two things a
+  host must not do — retry a failed refresh, or refresh concurrently — because a
+  replay revokes the entire grant and nothing in the failure says why;
+- the estate in this provider's own terms, including the cases where a
+  successful-looking run reaches nobody, or reaches the real one;
+- every action and trigger with its method, path, inputs, and whether it is safe
+  to replay;
+- a trigger's provider-side setup, which nobody can derive from anything else.
+
+It is **generated from `provider/manifest.json`**, so it cannot drift from what
+the packages do — which is the point at a few hundred providers, where a
+hand-written setup section is a few hundred documents going quietly stale.
+
+No code changed. This release exists because a registry and an installing agent
+read the PUBLISHED artifact, and the artifact carried the old README.
+
 ## [0.2.0] — 2026-08-24
 
 ### Changed
@@ -94,3 +128,4 @@ one.
 
 [0.1.0]: https://github.com/Fancy-Friends/hubspot/releases/tag/v0.1.0
 [0.2.0]: https://github.com/Fancy-Friends/hubspot/releases/tag/v0.2.0
+[0.3.0]: https://github.com/Fancy-Friends/hubspot/releases/tag/v0.3.0

package/README.md

@@ -27,6 +27,59 @@ dependencies.
 subject to the kit's full approval bar, and one per provider is hundreds of
 dependencies nobody is tracking.
 
+## Setting it up
+
+Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
+
+### Credentials
+
+A HubSpot connection holds 4 values.
+
+**Two kinds of value, and mixing them up matters.** A `provider` credential is ONE value for the whole installation — an OAuth app's client secret serves every connected account. An `account` credential is one per connected account. A host that stores the second where it stores the first lets one account's credentials reach another's.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **App client ID** | per installation | not secret | From your HubSpot app's Auth tab. ONE value for the whole installation -- the same app serves every connected account. |
+| **App client secret** | per installation | **secret** | From the same Auth tab. Used to exchange the code and to refresh; never sent with an API request. |
+| **Access token** | per connected account | **secret** | Obtained by the host's OAuth exchange, PER CONNECTED ACCOUNT. Expires after 30 minutes -- a host that does not refresh will work all afternoon and be broken by morning. |
+| **Refresh token** *(optional)* | per connected account | **secret** | Also per account. Does not expire, so it is the credential worth protecting most: it mints access tokens indefinitely until the install is revoked. |
+
+### Authorising
+
+HubSpot uses OAuth2 (authorization_code). The package DECLARES the exchange; the HOST performs it — a consent screen needs a browser, a redirect URI and somewhere to persist the result, and all three belong to the host.
+
+- **Authorize URL** — https://app.hubspot.com/oauth/authorize
+- **Token URL** — https://api.hubapi.com/oauth/v1/token
+- **Scopes** — `crm.objects.contacts.write`
+- **Access token lifetime** — 1800 seconds (30 minutes). A host that never refreshes works all afternoon and is broken by morning.
+
+The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
+
+### The estate
+
+HubSpot has a test estate on the same host, reached with credentials from a SEPARATE test account you register. Selecting sandbox mode uses those credentials.
+
+> HubSpot's test estate is a DEVELOPER TEST ACCOUNT: a separate portal you create from the developer account, with its own portal id, its own data and its own OAuth install. Same API host, different account -- so the credential is different and the URL is not. Test accounts expire if unused and carry reduced limits, which is why they are a place to test rather than a place to build against.
+
+## What it can do
+
+### Actions
+
+#### `contact_create` — Create contact
+
+Create a contact in HubSpot.
+
+`POST /crm/v3/objects/contacts` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `email` | yes | HubSpot de-duplicates contacts on email within an account. A contact created without one cannot be de-duplicated, and a retry will make a second. |
+| `firstName` | no | First name |
+| `lastName` | no | Last name |
+| `company` | no | Company |
+| `phone` | no | Phone |
+| `lifecycleStage` | no | HubSpot's own stage names. A value it does not recognise is refused at write time, not at setup. |
+
 ## Run it before you have credentials
 
 Every operation ships a **faker**, whether or not HubSpot has a sandbox. Set a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/hubspot-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "HubSpot for Node — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP on @particle-academy/fancy-connector-core; no vendor SDK.",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
   },
   "peerDependencies": {
     "@particle-academy/fancy-flow": ">=0.47.1 <2.0",
-    "@particle-academy/hubspot-ui": "0.2.0"
+    "@particle-academy/hubspot-ui": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@particle-academy/fancy-flow": {