@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-connector-builder/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: uipath-connector-builder
+description: "UiPath Integration Service connector authoring (REST+JSON) on disk via `uip is connectors builder`. Triggers on `element.json`, `element-metadata.json`, `standard-resources/*.json`, a `periodic-uipath-*`/`periodic-design-*` connector repo, or any request to build/edit an IS connector: init the connector shell, configure auth (14 types via `auth set`), add activities with fields/params/methods/hooks, wire polling/webhook triggers, add auth-system resources, inspect, validate, and surgically read/write files via state. Import + publish live on the parent `uip is connectors` (need `uip login`). NOT for operating a published connector — connections, ping, run an activity→uipath-platform; NOT for `.flow` connector nodes→uipath-maestro-flow."
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# Connector Builder
+
+Author UiPath Integration Service connectors on disk with `uip is connectors builder`, then `import` + `publish` them through the parent `uip is connectors`. A connector is a `periodic-*` repo (`periodic-uipath-{vendor}-{product}` for official; `periodic-design-{org}-{slug}` for custom — `init` derives the `design-{org}-{slug}` element key from `--name` + `--organization`) whose core is `app/element/element.json` plus `standard-resources/*.json` and JavaScript `hooks/`. Connectors wrap **REST APIs that return JSON only** — no SOAP, GraphQL, or XML. Terminology: the authoring noun is **activity** (it maps to an element.json resource + a standard-resource file).
+
+## When to Use This Skill
+
+- Creating a new connector from a vendor's API docs (init → auth → activities → validate → import → publish).
+- Editing an existing connector: adding activities, fields, parameters, methods, or hooks.
+- Configuring or switching authentication (OAuth2, PKCE, client credentials, API key, basic, JWT, AWS v4, etc.).
+- Writing or fixing JavaScript request/response hooks.
+- Wiring a polling or webhook trigger on an existing activity.
+- Debugging a connector, activity, hook, or trigger problem in `element.json` / a standard-resource file.
+- Validating before release, or pulling/pushing a design connector to a tenant.
+
+## Critical Rules
+
+1. **Inspect before editing.** On any existing connector, run `builder inspect` first to map auth, config, activities, hooks, and triggers. Never edit blind. Never invent config keys, activity paths, or IDs — read state first (`inspect`, `activity list`, `state query`).
+2. **Validate before you finish.** Run `builder validate` at the end of every workflow and after each fix — it runs the full periodic check set and exits non-zero on failure. On failure, read the reported field, fix that one entry, re-validate. After 3 failed attempts on the same error, stop and surface the `validate` output — don't keep guessing. **Don't stop at "0 errors": read the WARNINGS too** — they flag real gaps that still ship a half-built connector (a fieldless activity, a broken SR link). Treat them as must-fix unless you can articulate why a given one is acceptable.
+3. **`auth set` owns all authentication.** It writes the config entries, `authentication.type` / `typeOauth` / `authenticationTypes`, and the token-refresh resource in one call. Define scopes here too (`--scope`, `--scope-options`, `--required-scopes`, `--preselected-scopes`) — there is no separate scope command. `init --auth oauth2|customApiKey` is inline sugar for the create-time common case; everything else goes through `auth set`. Never hand-roll auth via `state patch`.
+4. **`activity create` writes both sides in one call** — the standard-resource file AND one `element.json` entry per method. Re-running on an existing activity appends/merges. Pass `--skip-sr` (or use `auth system create`) only for system resources that need no SR file. Model `GETBYID`/`PATCH`/`PUT`/`DELETE` only for TRUE by-id endpoints — never for search. The `/{primaryKey}` path param is added automatically: ALWAYS for `GETBYID`, and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also has a `GET`/`GETBYID`); a write-only/action activity keeps its base path.
+5. **`state patch` REPLACES the whole node at a pointer (no merge).** To change one field: `state query` the entry, edit it, then `state patch` the COMPLETE object back. `element-metadata.json` has no addressable sub-paths — round-trip the whole file. Activity paths in pointers are URL-encoded: `/contacts` → `%2Fcontacts`. Use the dedicated authoring verbs for creation, not `state patch`.
+6. **Connector targeting.** Builder verbs walk up from the cwd, then scan immediate subdirectories — run from inside the connector dir, or pass `--connector-dir <PATH>` to target one explicitly (required when multiple connectors are nearby). `import` reads `--connector-dir` the same way (the connector root holding `app/element/element.json`); on `download` it instead names the OUTPUT directory to write the pulled connector into. **Exception — `init` does NOT scan subdirectories** (it would otherwise resolve a SIBLING connector and silently EDIT/rename it): to CREATE, run `init` from a fresh/empty directory (a dir that merely *contains* connector subdirs — e.g. `/tmp` — creates a new connector, it will not dive into a child to edit it); to EDIT, run from inside the connector or pass `--connector-dir`.
+7. **Output is the `{Result, Code, Data}` envelope.** Add `--output json` to parse it. Failures exit non-zero. Never suppress stderr.
+8. **`import` / `download` / `publish` — and `init` when CREATING — need `uip login`.** Authenticate before any tenant pull/push. A NEW connector's key `design-{org}-{slug}` takes its org from your logged-in session, so `init` create ERRORS when you're not logged in. Let it derive the org; do NOT pass a guessed `--organization` (a wrong org bakes into the key and only surfaces, mismatched, at import/publish) — `--organization <slug>` is only for offline/CI builds with a known org.
+9. **Never echo, log, or hard-code a secret.** Secret config keys (client secret, API key, password, token) are written by `auth set` ENCRYPTED (`encrypt: true`) — most as `PASSWORD` fields, though some (OAuth tokens, a service-account JSON) are encrypted `TEXTFIELD`/`TEXTAREA`. End users supply real credentials at connection time; the connector holds only the auth TYPE + endpoint URLs + scopes. Use placeholders in every example command.
+10. **Prefer a built-in over a hook.** Before writing JS, consult the decision table ([references/hooks.md](references/hooks.md) §"Decide first: hook or built-in?") — a hook is only for transforms, orchestration, or derivation no declarative feature expresses. One hook file per activity+method+phase; hooks run in Denali (modern JS + `require('axios')` for secondary calls) and must end every path with `done()`.
+11. **Author the field schema for EVERY activity — `activity create` does NOT infer fields.** An activity with no fields renders in Studio Web as a single raw JSON body in and raw JSON out, with zero typed inputs/outputs — a half-built connector that still validates and publishes, so the omission is easy to miss (it's a recurring failure: "got it valid and published" while skipping the schema). After `activity create`, ALWAYS define the request/response fields from the vendor's documented schema — either pass `--fields-file <json>` on `activity create` for the whole schema at once, or add them one at a time with `activity field create`. `validate` emits a WARNING for any fieldless activity — treat it as must-fix. Never report a connector "done" with fieldless activities; if a raw-body passthrough is genuinely intended, say so explicitly.
+
+## Connection design (host, region, discovered values)
+
+Decide how each per-connection value reaches the request BEFORE scaffolding — getting this wrong is the most common rework:
+
+- **One config drives the host — not three URLs.** When the base, token, and authorize hosts share a per-connection part (an instance name, region, datacenter, or workspace), surface ONE config and template it into every URL: `init --base-url 'https://{instance}.../api'` + `auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'`. The CLI auto-seeds a single fillable `{instance}` field that resolves all three ([references/configuration.md](references/configuration.md) §Templated hosts). Do NOT expose `base.url`/`oauth.token.url`/`oauth.authorization.url` as separate connection fields.
+- **Open value → TEXTFIELD; fixed set → COMBO.** A free-form instance/workspace/account name is the auto-seeded templated TEXTFIELD — that is a legitimate, common shape, not a smell. Only a genuinely fixed datacenter/environment list becomes a COMBO (`state patch` the seeded entry to `type:COMBO` with `options`, whose `value` can be the host fragment itself).
+- **Derive or discover before you ask.** If a per-connection value (the API host, an org/account id) is returned in the token response or is discoverable via an authenticated call, capture it instead of adding a manual field — but ONLY when it is genuinely needed AND obtainable; a single templated config is the simpler default, so don't over-engineer discovery where a plain field suffices. Token-response host → a `postRequest` hook that validates (https + allowlisted host, never log the token) and persists via `done({configuration})` — recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …". Discoverable id → an `onProvision` system resource that calls the lookup at connection time ([references/system-resources.md](references/system-resources.md)).
+- **Multi-datacenter OAuth:** the accounts/token host itself varies by region — template the region config into `--token-url`/`--authorization-url` too, not just the base URL.
+
+## Workflows
+
+Each workflow is an ordered sequence of copy-paste-ready commands. Use placeholders (`<ORG>`, `https://api.example.com`) — never real secrets.
+
+### New connector (full lifecycle)
+```bash
+# 0. Log in FIRST. The key `design-{org}-{slug}` takes its org from your logged-in
+#    session, so `init` (create) ERRORS if you're not logged in. Let it derive the
+#    org — do NOT guess --organization (a wrong org bakes into the key and only
+#    surfaces, mismatched, at import). --organization <slug> is for offline/CI only.
+uip login status            # check Data.Status == "Logged in" — NOT the envelope
+                            # Result/exit, which is "Success" even when the session
+                            # is dead (refresh-failed / expired). (`init` create
+                            # itself re-checks the live login status and blocks.)
+
+# 1. Scaffold the shell. --name is required when creating; key + folder are derived
+#    (the org comes from your login — see step 0).
+uip is connectors builder init --name 'Acme Widgets' \
+  --description 'Acme Widgets connector' --categories 'CRM,Sales and marketing' \
+  --base-url https://api.acme.com --auth oauth2 \
+  --authorization-url https://acme.com/oauth/authorize \
+  --token-url https://acme.com/oauth/token --scope 'read write'
+#   --categories must be approved DISPLAY-NAME values (e.g. 'CRM', 'Sales and marketing',
+#   'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like `crm,sales`.
+#   Validated at init AND `validate`: wrong case is canonicalized, an unknown value fails fast
+#   and the error lists the approved enum. init seeds element-metadata.json:latestVersion = "1.0.0".
+
+# 2. Add an activity (writes element.json entries + standard-resources/accounts.json).
+uip is connectors builder activity create --name accounts --vendor-path /v1/accounts \
+  --methods GET,GETBYID,POST,PATCH,DELETE --primary-key id --has-ceql
+
+# 3. Author the field schema — REQUIRED, not optional (Rule 11). `activity create`
+#    does NOT infer fields; without this the activity ships as a raw JSON body and
+#    `validate` warns. Pass `--fields-file <json>` on `activity create` for the whole
+#    schema at once, or add fields one at a time with `field create`
+#    (visibility flags apply to every --method listed; re-runs merge):
+uip is connectors builder activity field create --resource accounts --name email \
+  --type string --method GET --method POST --response
+
+# 4. Validate — must be 0 errors AND no unresolved warnings (fieldless activity,
+#    broken SR link) before import.
+uip is connectors builder validate
+
+# 5. Import (create-or-update on the tenant) then publish.
+uip login
+uip is connectors import
+uip is connectors publish --wait        # blocks until SUCCESS; live in Studio Web then
+                                        # (fire-and-forget without --wait: allow ~5-10 min)
+```
+Publishing a NEW connector needs no `--version` (init seeded `1.0.0`). **Re-publishing** an existing connector requires a HIGHER version — bump `element-metadata.json:latestVersion` (or pass `--version 1.0.1`); the server rejects an equal version.
+
+### Add an activity to an existing connector
+```bash
+uip is connectors builder inspect --output json     # map what exists first
+# research the vendor API, then:
+uip is connectors builder activity create --name contacts --vendor-path /v1/contacts \
+  --methods GET,GETBYID,POST --primary-key id --fields-file ./contacts-fields.json
+uip is connectors builder activity field create --resource contacts --name status \
+  --type string --method GET --response --searchable
+uip is connectors builder activity hook create --resource-name contacts --method GET \
+  --hook-type postRequest --custom-code-file ./contacts-postRequest.js   # optional response shaping (you write the JS)
+uip is connectors builder validate
+```
+
+### Add a polling trigger
+`trigger create` authors a POLLING trigger. The target activity must already exist and have an SR file (`trigger create` hard-fails otherwise).
+```bash
+uip is connectors builder activity list --output json    # confirm the activity exists
+uip is connectors builder trigger create --resource-name accounts --event-kind polling \
+  --updated-date-field LastModifiedDate --id-field Id     # seeds the event config + hasEvents flag
+uip is connectors builder validate
+```
+`--updated-date-field` is REQUIRED for every `--event-kind` — the command always authors a polling loop. `--event-kind polling|webhook|all` (default `polling`) only picks the config bundle; `webhook`/`all` add webhook config keys but don't implement delivery. Webhook delivery, the polling-vs-webhook semantics, and per-flag defaults all live in [references/events.md](references/events.md).
+
+### Customize a curated activity
+`activity create` auto-curates every method into a standalone Studio activity by default (opt out with `--no-curate`). Use `method curate` only to override the generated name/displayName, or to curate a `--no-curate` method.
+```bash
+uip is connectors builder activity method curate --resource cases --method GET \
+  --display-name 'Get Support Request'
+uip is connectors builder activity field create --resource cases --name subject --type string \
+  --method GET --response --response-curated --design-position primary
+uip is connectors builder validate
+```
+
+### Debug
+```bash
+uip is connectors builder inspect --output json
+# state patch REPLACES the node — query the WHOLE entry, change ONLY the field at fault, patch it ALL back:
+uip is connectors builder state query element.json/configuration/oauth.token.url --output json
+uip is connectors builder state patch element.json/configuration/oauth.token.url \
+  --value '<full entry from the query above, with defaultValue corrected>'
+uip is connectors builder validate
+```
+For a derived base URL (e.g. Salesforce `instance_url` from the token response): a `postRequest` hook VALIDATES the URL (https + allowlisted host) and persists it with `done({configuration})` — NOT `state patch`, which baking-time-edits one org's URL into every connection. Full recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …"; investigation checklists: [references/debugging.md](references/debugging.md).
+
+## Command Map
+
+```text
+uip is connectors                      # tenant/catalog + design-connector lifecycle (needs `uip login`)
+  list | get <key> | swagger <key> | export <key> | audit-logs | event-operations
+  download <key> | import | publish | publish-status <id> | probe
+  builder                              # author a connector ON DISK
+    init                               # create-or-EDIT the connector shell in ONE verb
+                                       #   (folds the old scaffold / metadata / global / base+pagination preset)
+        preset apply --kind base|pagination
+        header delete <vendorName>
+    auth     set | get | system (create|list)
+    activity create | list | get | delete
+             field  (create|list|get|delete)
+             method (get|set|curate)
+             param  (create|list|get|delete)
+             hook   (create|list|get|delete)
+    trigger  create                    # --event-kind polling|webhook|all (folds the event preset + polling)
+    inspect                            # read-only whole-connector rollup
+    validate                           # full check set; exits non-zero on failure
+    state    query <pointer> | patch <pointer>
+```
+
+`publish` returns a `PublishId`; `--wait` polls to SUCCESS/FAILURE (timeout via `--timeout-seconds`, default 600); check later with `publish-status <id>` (positional). Status enum: `IN_PROGRESS | SUCCESS | FAILURE`.
+
+## Reference Navigation
+
+Depth lives in `references/` — each self-contained. SKILL.md owns the workflows, command map, and rules above; references must not repeat them. The always-current flag source is `uip is connectors builder <noun> <verb> --help`.
+
+| Task → read this | Reference |
+|---|---|
+| What a connector is, file layout, the CRUD/curated/HTTP activity model | [references/overview.md](references/overview.md) |
+| element.json internals: top-level fields, resources[], parameters[], value interpolation, hook order | [references/element-json.md](references/element-json.md) |
+| Standard-resource files: linking, metadata.method, curated, fields (visibility/design/searchable) | [references/standard-resources.md](references/standard-resources.md) |
+| configuration[] entries: widget types, screen types, per-auth key sets, pagination + event keys | [references/configuration.md](references/configuration.md) |
+| Authentication setup: all 14 auth types and the OAuth/JWT scope surface | [references/auth.md](references/auth.md) |
+| Auth-system resources: auth-validation, onProvision/onDelete, OAuth token overrides | [references/system-resources.md](references/system-resources.md) |
+| When to write a hook vs use a built-in (decision table + good/avoidable patterns), execution order, context vars, done(), naming | [references/hooks.md](references/hooks.md) |
+| Polling and webhook triggers: config keys, event.poller.configuration schema | [references/events.md](references/events.md) |
+| Debugging auth / activity / hook / trigger / pagination issues (workflow + checklists) | [references/debugging.md](references/debugging.md) |
+
+## Anti-patterns
+
+1. Editing without `builder inspect` first (Rule 1) — you'll invent keys/paths that don't exist.
+2. Hand-rolling auth via `state patch` instead of `auth set` (Rule 3) — leaves the auth block inconsistent.
+3. Editing a config entry with a partial value (Rule 5) — `state patch` REPLACES the node, dropping omitted fields. Query the whole entry and patch the complete object back.
+4. Re-running `activity create` with a name that already exists when you meant a SEPARATE activity — it's an idempotent upsert that MERGES into the same-named activity (appends methods, preserves existing field definitions unless `--overwrite-fields`); it does not error, so a wrong name silently merges instead of warning.
+5. Modeling `GETBYID` for a search/list endpoint (Rule 4) — by-id verbs auto-add the `/{primaryKey}` param; reserve them for true single-record reads.
+6. Putting a real secret in an example or expecting the connector to store one (Rule 9) — secrets are encrypted fields (usually PASSWORD) supplied at connection time.
+7. Re-publishing without bumping the version — the server rejects an equal version; bump `latestVersion` or pass `--version`.
+8. Invented `--categories` values — they must come from the approved enum; `validate` reports the list.
+9. Writing a hook for a job a built-in does (Rule 10; hooks.md §"Recognizing an avoidable hook"), or omitting the trailing `done()` so the hook never returns.
+10. Reaching for a removed command — there is no `connector scaffold/inspect/validate` wrapper (use `init`/`inspect`/`validate` directly), no `global`/`metadata`/`config`/`resource*`/`event polling add`/`auth scope`/`remote*`/`describe`/`reference`.
+11. Reporting a connector "done" with fieldless activities (Rule 11) — `activity create` writes endpoints/methods/auth but NOT the field schema; an activity with no `field create` / `--fields-file` shows only a raw JSON body in Studio and trips a `validate` WARNING. Author fields before finishing, and never treat a 0-error/has-warnings validate as a pass.

package/skills/uipath-connector-builder/references/auth.md

@@ -0,0 +1,171 @@
+# Authentication in UiPath Integration Service connectors
+
+A connector's authentication block tells Integration Service which auth flow to run when a
+tenant creates a connection. `auth set` writes all of it in one call: the **config entries**
+in `element.json → configuration[]` (one per credential/endpoint URL — these render the
+connection form AND drive the OAuth dance / API-key wiring) plus the **top-level fields**
+`authentication.type`, `typeOauth`, `elementMetadata.authenticationTypes` (which select the
+flow). The definition holds only the auth TYPE, endpoint URLs, and scopes — never real creds.
+
+## SECURITY — secrets are never stored in the connector
+
+Secret config keys (client secret, API key, password, token) are written by `auth set` with
+`encrypt: true` — encrypted at rest and redacted in responses. Most are `type: PASSWORD` +
+`isPrivate: true` (also masked); some sensitive values use a non-PASSWORD widget but stay
+encrypted — e.g. an OAuth user token (`TEXTFIELD`) or a Google service-account JSON
+(`TEXTAREA`). Rules:
+
+- NEVER echo, `cat`, log, or print a secret value. `auth get` / `inspect` return the config
+  SHAPE, not the value — there is nothing to dump.
+- NEVER put a real secret in an example command. Use placeholders (`<CLIENT_ID>`, the
+  vendor's header name) — secret VALUES are not part of the connector at all.
+- The tenant user supplies `client id`, `client secret`, `api key`, etc. at connection time.
+
+## Auth types (`auth set --auth-type`)
+
+All 14 types are supported. `init --auth` is sugar for the two most common (`oauth2`,
+`customApiKey`) at create time; everything else (and the full flag surface) goes through
+`auth set`.
+
+| auth-type               | Use when                                        |
+|-------------------------|-------------------------------------------------|
+| oauth2                  | OAuth 2.0 Authorization Code flow.              |
+| oauth2Pkce              | OAuth 2.0 Authorization Code + PKCE.            |
+| oauth2ClientCredentials | OAuth 2.0 Client Credentials (no user).         |
+| oauth2Password          | OAuth 2.0 Resource Owner Password.              |
+| oauth1                  | OAuth 1.0a / Token-Based Authentication (TBA).  |
+| basic                   | HTTP Basic (username + password).               |
+| jwtOauth                | JWT-bearer OAuth.                               |
+| jwtOauth2               | JWT-bearer OAuth 2.0.                           |
+| custom                  | A custom static authorization header.           |
+| customApiKey            | Vendor uses a static API key (header or query). |
+| personalAccessToken     | Personal access token authorization header.     |
+| awsv4                   | AWS Signature v4.                               |
+| googleServiceAccount    | Google service-account JSON.                    |
+| rsaCertificate          | RSA private-key certificate.                    |
+
+Per-type config key sets (which secrets, which URLs) are in
+[configuration.md](configuration.md) §"Auth as configuration".
+
+## OAuth 2.0 (authorization_code)
+
+```bash
+uip is connectors builder auth set --auth-type oauth2 \
+  --authorization-url https://acme.com/oauth/authorize \
+  --token-url https://acme.com/oauth/token \
+  --scope 'read write'
+```
+- `--authorization-url`, `--token-url`, `--scope` are the core flags.
+- `--token-refresh-url` defaults to `--token-url`; `--token-revoke-url` is optional.
+- **Extra authorize query params need NO script** — append them to `--authorization-url`
+  directly; they are preserved verbatim. Use this for vendors that require a refresh-token opt-in
+  on the consent URL: Dropbox `?token_access_type=offline`, Zoho `?access_type=offline`,
+  Google `?access_type=offline&prompt=consent`.
+- A per-region/instance/workspace host belongs in the URL as `{placeholder}` (e.g.
+  `https://accounts.{environment}/oauth/v2/token`) — the CLI auto-seeds a backing config; see
+  [configuration.md](configuration.md) §"Templated hosts". No hook needed.
+- For refresh-token OAuth types (not client credentials), `auth set` also creates an
+  `oauthOnTokenRefresh` system resource pointing at the refresh URL.
+
+## OAuth / JWT scope surface (FLAGS on `auth set` — there is NO `auth scope` command)
+
+`--scope` always sets the default scope string. To make scopes USER-SELECTABLE (the
+`oauth.scope` MULTISELECT with options/required/preselected), the TRIGGER is `--scope-options`
+(or `--scope-options-file`) OR `--required-scopes` — without one of those the MULTISELECT
+override is NOT built. The remaining flags are modifiers that take effect ONLY once the
+override exists, so `--preselected-scopes` (or `--scope-delimiter`/`--scope-hint-text`/
+`--scope-screen-type`) ALONE does nothing. Pass them on the SAME `auth set` call (or re-run
+with `--force`):
+
+| Flag | Purpose |
+|------|---------|
+| `--scope <str>` | Space-delimited scope string (the default scope value). |
+| `--scope-options <json>` | JSON array of `{description,value}` selectable options. |
+| `--scope-options-file <path>` | Read `--scope-options` JSON from a file. |
+| `--required-scopes <csv>` | Scopes the user cannot deselect. |
+| `--preselected-scopes <csv>` | Scopes pre-checked by default. |
+| `--scope-delimiter <char>` | Scope separator (default: space). |
+| `--scope-hint-text <text>` | Hint shown under the scope selector. |
+| `--scope-screen-type <type>` | configScreenType for the scope entry (default: pre). |
+
+```bash
+uip is connectors builder auth set --auth-type oauth2 \
+  --authorization-url https://acme.com/oauth/authorize \
+  --token-url https://acme.com/oauth/token \
+  --scope 'read write' \
+  --scope-options '[{"description":"Read","value":"read"},{"description":"Write","value":"write"}]' \
+  --required-scopes read --preselected-scopes read,write
+```
+
+## customApiKey
+
+```bash
+uip is connectors builder auth set --auth-type customApiKey \
+  --api-key-param-name X-API-Key --api-key-location header \
+  --validation-vendor-path /me      # provisionAuthValidation (see below) — recommended for static auth
+```
+- `--api-key-param-name` (required): vendor header/query name (`X-API-Key`, `Authorization`,
+  `subscription-key`) from vendor docs.
+- `--api-key-location`: `header` (default) or `query`. `--api-key-prefix`: literal prefix
+  prepended to the value (e.g. `Bearer `).
+- `--key-config-name`: internal config key (default `custom.api.key`). `--key-config-display-name`:
+  UI label (default `API Key`).
+
+What it writes (the PASSWORD secret entry + the `type:"value"` parameter mapping
+`${configuration.<name>}` into the vendor header/query): [configuration.md](configuration.md) §"Auth as configuration".
+
+## Multiple credential headers (any auth type) — `--auth-header` / `--secret-auth-header`
+
+Some vendors authenticate with SEVERAL static headers (e.g. iContact: `API-AppId`, `API-Username`,
+`API-Password`, `API-Version`). `auth set` (esp. with `--auth-type custom`) takes repeatable flags —
+no script, no `state patch`:
+
+```bash
+uip is connectors builder auth set --auth-type custom \
+  --auth-header AppID=API-AppId \
+  --auth-header api.username=API-Username \
+  --secret-auth-header api.password=API-Password
+```
+
+Each `ConfigName=VendorHeader` writes a `pre`/required config entry (`--secret-auth-header` makes it a
+PASSWORD/encrypted) plus a global `${configuration.<ConfigName>}` → vendor-header parameter. The tenant
+user fills each on the connection form. Static (non-credential) headers like `API-Version` or
+`Content-Type` go through `init --header VendorName=value` (a `type:"value"` param). Bespoke config keys
+ARE accepted by the backend (the catalogue connectors use them) — just declare them through these flags
+rather than hand-editing `configuration[]`.
+
+## Auth-validation probe (any type)
+
+`--validation-vendor-path <path>` (with optional `--validation-method`, default GET) seeds
+a `provisionAuthValidation` system resource — one read-only call at connection creation that
+rejects bad creds immediately. The probe must be read-only and must not change vendor data,
+so keep it GET. Every non-OAuth/JWT auth type (any whose name isn't `oauth*`/`jwt*` — `basic`,
+`custom`, `customApiKey`, `personalAccessToken`, `awsv4`, `googleServiceAccount`,
+`rsaCertificate`) has no token exchange to catch bad creds, so `validate` flags it as missing
+there. Details: [system-resources.md](system-resources.md) §provisionAuthValidation.
+
+## System (lifecycle) resources — `auth system`
+
+Lifecycle/auth-flow endpoints with no SR file (provisionAuthValidation, onProvision,
+oauthOnTokenRefresh, …) are wired with `auth system create --type <type>` / `auth system list`.
+The full type list, override-path rules, and flags: [system-resources.md](system-resources.md).
+
+## Base URL derived from a token response (e.g. Salesforce `instance_url`)
+
+There is NO vendor-specific base-url flag (`init --base-url` is STATIC only). When the vendor
+returns the API host in its token response, it is skill-guided: a `postRequest` hook reads +
+validates the host (https scheme, allowlisted), then persists it into THIS connection's config
+at runtime via `done({configuration})` — NOT `state patch` (that baking-time edit would set one
+org's URL as everyone's default). Full pattern: [hooks.md](hooks.md) §"Pattern: base URL …
+derived from a token response".
+
+## Re-running auth set
+
+Idempotent on identical inputs (returns `unchanged`). If a new input would modify an
+existing entry, it fails with a `configConflict` listing every diff — re-run with `--force`
+to apply. Use this to swap an existing connector's auth type.
+
+## See also
+- [configuration.md](configuration.md) — config keys per auth type, widget/screen types
+- [system-resources.md](system-resources.md) — auth-validation, token-refresh overrides
+- [element-json.md](element-json.md) — element.json structure and the authentication block

package/skills/uipath-connector-builder/references/configuration.md

@@ -0,0 +1,130 @@
+# Configuration Reference
+
+Config entries live in `element.json → configuration[]`. Authentication, pagination,
+and events are ALL config keys — their values are filled per-connection at creation time.
+
+## How configuration gets set (no `config create` command exists)
+
+There is no `config` command group. Configuration is authored by the verbs below — never
+hand-edit raw JSON when one of these covers it:
+
+| To set… | Use |
+|---|---|
+| Base URL, headers, accept/content-type, categories, lifecycle, tier | `init` (e.g. `init --base-url`, `init --header VendorName=value`, `init --accept-type`) |
+| Auth config keys + the `oauth.scope` MULTISELECT | `auth set` (see [auth.md](auth.md)) |
+| The base or pagination key bundle | `init preset apply --kind base \| pagination` |
+| The event/polling key bundle | `trigger create --event-kind polling \| webhook \| all` (NOT a config preset) — see [events.md](events.md) |
+| One bespoke entry, or a surgical edit to an existing entry | `state patch element.json/configuration/<key>` |
+
+### Presets
+
+```bash
+uip is connectors builder init preset apply --kind pagination
+uip is connectors builder init preset apply --kind base --override base.url=https://api.acme.com
+```
+- `--kind base` seeds the base URL + select/nulls/instance keys; `--kind pagination` seeds
+  the four pagination keys. `--override key=value` (repeatable) overrides a defaultValue.
+- `--force` applies diffs on entries that already exist instead of erroring.
+- There is NO `event` preset kind — the event bundle is seeded by `trigger create --event-kind`.
+
+### Surgical edits with `state patch`
+
+To change one config field, `state patch` the entry at
+`element.json/configuration/<key>` (e.g. `.../oauth.token.url`). `state patch` REPLACES the
+whole node — query first and patch the COMPLETE object back (SKILL.md Rule 5).
+
+## Config Entry Object
+`key` (dot-notation, e.g. `oauth.api.key`), `name`, `description`, `type` (widget),
+`defaultValue`, `required`, `internal` (system-set), `hide`, `hideFromConsole`,
+`encrypt` (secrets), `active` (true), `companyConfig`/`resellerConfig` (false),
+`isPrivate` (redact in responses), `displayOrder`, `configScreenType`.
+Optional: `groupControl`, `groupBy`, `options` (`[{"description","value"}]`),
+`design`, `hintText`.
+
+## Config Types (widgets)
+`TEXTFIELD_32|64|128|256|1000` (by max length; 128 = most fields, 1000 = URLs),
+`TEXTAREA` (keys/certs/JSON), `PASSWORD` (masked, auto-encrypt), `BOOLEAN`,
+`COMBO` (single-select), `MULTISELECT` (OAuth scopes), `CODE_EDITOR`.
+
+## Config Screen Types
+`"pre"` (must fill on creation), `"pre-optional"` (optional on creation), `"none"` (hidden).
+
+## Templated (per-instance / per-region / per-workspace) hosts — NO script needed
+When the API host differs per connection (Zoho's region `https://desk.{environment}/api/v1`,
+Databricks `{workspace.url}`, Sugar `https://{siteUrl}/rest/v11`), put a `{placeholder}` in the
+URL and back it with a configuration entry **keyed exactly the same** as the placeholder. At
+connection time IS substitutes `{placeholder}` with that config's value. This is the correct,
+scriptless way to handle dynamic hosts — do NOT reach for a hook.
+
+- Just template the URL on `init`/`auth set`: `init --base-url 'https://desk.{environment}/api/v1'`,
+  `auth set --token-url 'https://{workspace.url}/oidc/v1/token'`. The CLI **auto-seeds** a required
+  `TEXTFIELD_1000` config keyed by each placeholder (e.g. `environment`, `workspace.url`), screen
+  type `pre`, so the user fills it on the connection form.
+- A `{placeholder}` in **`base.url`** also gets an auto-seeded element-level **global path parameter**
+  (`{ vendorType:"path", vendorName:"<placeholder>", name:"<configKey>", type:"configuration" }` in
+  the root `parameters[]`). This is what actually substitutes the token into **every resource
+  request** — the backing config entry alone is NOT enough for `base.url` (it would only resolve the
+  OAuth call). The CLI seeds this on `init --base-url` / `auth set`; if you instead set `base.url`
+  by raw `state patch`, add the path parameter yourself.
+- `validate` HARD-ERRORS if a `{placeholder}` in any URL has no backing config key, AND if a
+  `base.url` placeholder has no global path parameter binding it — so an unresolvable host can never ship.
+- To upgrade the seeded TEXTFIELD into a **picker** (Zoho's datacenter dropdown), `state patch` the
+  entry to `type: COMBO` with `options: [{"value":"zoho.com","description":"zoho.com"}, …]`.
+- `${configuration.x}` (dollar-brace) is a value-REFERENCE into an existing config (e.g. an API-key
+  header param), NOT a host placeholder — it is not seeded.
+
+## Auth as configuration
+Authentication is config keys + `authentication.type`, all written by `auth set`. Secret
+keys (client secret, API key, password, token) are written with `encrypt: true` — encrypted
+and redacted; most are `PASSWORD` + `isPrivate` (masked), but some (OAuth tokens, a
+service-account JSON) are encrypted `TEXTFIELD`/`TEXTAREA`. They hold NO value in the
+connector; the tenant user supplies the real secret at connection time. Key sets per type:
+
+- **OAuth2** (16 entries — canonical list; `auth set` writes all of them):
+  `oauth.api.key`, `oauth.api.secret` (PASSWORD, encrypt, isPrivate), `oauth.callback.url`
+  (auto-set, do NOT hardcode), `oauth.authorization.url`, `oauth.token.url`,
+  `oauth.token.refresh.url`, `oauth.token.revoke.url`, `oauth.scope`,
+  `oauth.basic.header`, `oauth.user.token`, `oauth.user.refresh.token`,
+  `oauth.user.refresh.interval` (sec, default 3600), plus auto-set internals
+  `oauth.user.refresh.time`, `oauth.decode.authorization.code`, `authentication.time`,
+  `expires_in`. Sets `authentication.type:"oauth2"`, `typeOauth:true`.
+- **OAuth2 PKCE** adds `oauth.pkce.code.challenge.verifier`, `oauth.pkce.code.challenge`,
+  `oauth.pkce.code.challenge.method` (`"S256"`).
+- **OAuth2 Client Credentials**: subset — no auth URL, no refresh token.
+- **customApiKey** (the on-disk type for any "API key" auth — the UI labels it "API key",
+  but never use periodic's bare `apiKey`): one PASSWORD secret config (default
+  `custom.api.key`, encrypt, isPrivate, `groupBy:"customApiKey"`) + one `type:"value"`
+  parameter mapping `${configuration.<name>}` into the vendor header/query;
+  `authentication.type:"customApiKey"`, `typeOauth:false`. CLI flow + flags:
+  [auth.md](auth.md) §customApiKey.
+- **basic**: `username`, `password` (PASSWORD, encrypt).
+- **jwtOauth**: `jwt.oauth.consumer.key`, `jwt.oauth.private.key`, `jwt.oauth.username`,
+  `jwt.oauth.token.url`, `jwt.oauth.scope`. `typeOauth:true`.
+- **awsv4**: `aws.api.key`, `aws.api.secret`, `aws.region`, `aws.service.name`, `aws.host`.
+
+## Multi-auth (groupControl)
+An `authentication.type` COMBO with `"groupControl": true` plus per-type config entries
+tagged with `groupBy`. Fields without `groupBy` always show; comma-separated `groupBy`
+shows the field for multiple groups.
+
+## Scope entry (`oauth.scope`, MULTISELECT)
+Built by the `auth set --scope*` flags — only when `--scope-options`/`--scope-options-file` or
+`--required-scopes` triggers it (condition + flag list in [auth.md](auth.md)). The `design`
+block carries `requiredOptions` (cannot deselect), `preSelectedOptions` (pre-checked),
+`delimiter`, `enableUserOverride`; `options` is the `[{"description","value"}]` list.
+
+## Pagination keys (`init preset apply --kind pagination`)
+The pagination preset seeds exactly four keys: `pagination.max` (TEXTFIELD_32, default `100`),
+`pagination.type` (TEXTFIELD_32 — e.g. cursor/offset/page), `pagination` (TEXTFIELD_128, a
+pagination-config JSON string), and `pagination.page.startindex` (TEXTFIELD_32, default `1`).
+`base.url` and `filter.response.nulls` are seeded by the `--kind base` preset, NOT this one.
+`paginatorVersion` at top level selects the engine.
+
+## Event keys
+Polling/webhook config keys (`event.notification.*`, `event.vendor.type`, `event.poller.*`,
+`event.raw.enabled`) are seeded by `trigger create --event-kind` and documented in
+[events.md](events.md) §"Polling config keys" — the canonical list. They are ordinary
+`configuration[]` entries.
+
+## See also
+- [auth.md](auth.md), [system-resources.md](system-resources.md), [events.md](events.md)

package/skills/uipath-connector-builder/references/debugging.md

@@ -0,0 +1,80 @@
+# Connector Debugging Guide
+
+Workflow: `inspect` → understand → identify the misconfiguration → fix with a single
+addressed write → re-`validate`. Tooling: `inspect` (read-only rollup), `state query
+<POINTER>` (surgical read), `state patch <POINTER>` (REPLACES the whole node — to edit one
+field, query the entry and patch the complete object back), `validate` (full check set,
+exits non-zero on failure). All run under `uip is connectors builder`.
+
+## Investigation steps
+1. `inspect` — auth types, config, resources (with SR files + hooks), global hooks, events, metadata.
+2. `state query` the relevant slice:
+   - Auth → `element.json/authentication`, `element.json/configuration`, then `.../configuration/{key}`
+   - Resource → `element.json/resources`, then `.../resources/{METHOD}/{url-encoded-path}` + `standard-resources/{name}`
+   - Hook → `hooks/{file}.js` + `element.json/resources/{M}/{P}/hooks`
+   - Event → `element.json/configuration/event.poller.configuration` + `standard-resources/{name}/metadata/events`
+3. Cross-reference: resources[] ↔ SR files (paths match), hook `ref`s ↔ `hooks/` files,
+   configuration[] ↔ auth-type requirements, element-metadata flags ↔ capabilities.
+4. `validate` for automated pass/fail (use this to gate, not `inspect`).
+
+## Connection issues
+- **OAuth redirect loop / error**: wrong `oauth.authorization.url` (often the token URL by
+  mistake), missing scopes, hardcoded `oauth.callback.url` (periodic sets it), `typeOauth`
+  false when it should be true.
+- **Token exchange fails**: wrong `oauth.token.url`; vendor expects/rejects
+  `oauth.basic.header`; creds in wrong place (body vs header).
+- **Works then fails after expiry**: `oauth.token.refresh.url` unset, refresh interval too
+  long, or wrong param mapping in `oauthOnTokenRefresh`.
+- **API key unauthorized**: wrong header name, missing prefix (`Bearer `/`Token `), or key
+  sent as query when the vendor wants a header. Re-run `auth set --auth-type customApiKey`.
+
+## Resource (activity) issues
+- **Empty results**: wrong `vendorPath`, wrong response `root-key`, postRequest hook filters
+  wrongly, or broken pagination.
+- **404**: `vendorPath` typo/version, path-param mismatch, wrong/missing `base.url`,
+  deprecated endpoint.
+- **Create/Update sends wrong data**: request body wrapped in the wrong key, preRequest hook
+  mangles the body, IS↔vendor field-name mismatch.
+- **Fields don't show in Studio**: missing `--request-curated`/`--response-curated` on the
+  `activity field create` call, or the field is `--hidden`.
+- **Object shows in Studio but has NO methods under it**: the SR method's path points at the
+  VENDOR path, not the IS slug `/<object>`, so periodic can't link it; `validate` flags "SR
+  linkage broken". Fix: set the SR method's `reference` (or `path`) to the IS slug `/<object>`
+  so it matches the element.json resource path. See [standard-resources.md](standard-resources.md).
+- **Methods aren't curated activities**: a method created with `--no-curate` has no `curated`
+  block — re-run `activity create` (curates by default) or `activity method curate`.
+- **by-id confusion**: GETBYID/PATCH/DELETE auto-add the `/{primaryKey}` path param; only
+  model GETBYID for TRUE by-id endpoints, not search.
+
+## Hook issues
+- **done() not called**: an exception or a branch skips `done()`.
+- **Hook not applied**: not registered in element.json (run without `--no-auto-register`),
+  `ref`/filename mismatch (case-sensitive), wrong `type` or resource/method.
+- **Global hook over-applies**: re-create it scoped to the resource instead of `--global`.
+- **Hook throws / 500 from a hook**: a real JS error, or a `require()` of a module Denali doesn't provide (it supports `axios`/`crypto`/`url`/`querystring`/`lodash`/`moment`). Modern JS (`?.`, `??`, `async`/`await`) is fine. See [hooks.md](hooks.md).
+
+## Event / pagination issues
+- **Events not working**: `hasEvents` unset, missing event config keys, malformed
+  `event.poller.configuration` JSON. Re-run `trigger create` to re-seed the bundle.
+- **Polling returns everything**: missing date filter in the URL, wrong `--updated-date-field`,
+  or date-format mismatch. See [events.md](events.md).
+- **Only first page**: wrong `--pagination-type`, missing `--next-page-key`/`--root-key`, or
+  missing nextPage handling in a preRequest hook.
+
+## Publish / import issues (tenant lifecycle — under `uip is connectors`, NOT builder)
+`import` → `publish` order and the `publish`/`--wait`/`publish-status` mechanics live in
+SKILL.md; the symptoms below are debug-only:
+- **Local edits not reflected after publish**: `publish` promotes what was already imported —
+  it does NOT push local file changes. Re-`import` first, then `publish`.
+- **"version must be higher"**: re-publishing needs a HIGHER version than the last published
+  one. Bump `element-metadata.json:latestVersion` (or pass `--version 1.0.1`). A brand-new
+  connector publishes with NO `--version` (`init` seeds `latestVersion = "1.0.0"`).
+- **Published but not visible**: Studio Web shows a fresh publish ~5–10 min after `SUCCESS`.
+- **Live smoke test**: `uip is connectors probe --connection-id <id>` proxies each on-disk SR
+  through a real connection (GET-only; `--include-mutations` to add POST/PUT/PATCH/DELETE).
+  Catches `metadata.method.<VERB>.path` typos that static `validate` cannot.
+- **Auth**: `import` / `download` / `publish` / `publish-status` / `probe` all require `uip login`.
+
+## See also
+- [hooks.md](hooks.md), [events.md](events.md), [configuration.md](configuration.md),
+  [standard-resources.md](standard-resources.md), [system-resources.md](system-resources.md)