Build with LLM
Collez le prompt ci-dessous dans Claude Code, Codex ou Cursor pour construire, dans votre projet, un client back-end pour la Process API de Human Plugin. Le prompt couvre le flux api+humantoken, dans lequel votre système envoie le selfie. Le flux humantoken exige qu'une personne ouvre un lien : l'agent s'arrête donc à cette étape et vous la confie.
# Build a Human Plugin Process API client
## Role and objective
You are an integration engineer. Build a back-end client for the Unico Human Plugin Process API in this repository: create a process, read it until it reaches a final state, and optionally fetch the selfie. Use only the facts in this prompt. If something is not stated here, do not invent it; ask the developer.
## Facts you can rely on
- Human Plugin is one container you run yourself, with your own PostgreSQL. The default base URL is plain HTTP on port 8080, for example `http://human-plugin.internal:8080`.
- It has NO caller authentication, NO TLS, NO webhook, and no list, search, or delete endpoint. Callers must be restricted by the network. Never call it from a browser or mobile app.
- Bodies are JSON, field names are camelCase. Errors look like `{"message":"INVALID_REQUEST","details":[]}`.
- Endpoints:
- `POST /v1/processes` creates a process and answers `201` with a `Location: /v1/processes/<id>` header.
- `GET /v1/processes/{id}` returns `{id, state, data}`. `{id}` is the UUID Human Plugin returned.
- `GET /v1/processes/{id}/selfie` returns `{"fileContents":"<base64>","contentType":"image/jpeg"}`.
- `GET /health/live` and `GET /health/ready` return `{"status":"ok"}`. Ready also checks PostgreSQL and answers `503` when it is down. Ready does not verify the Unico access key.
- States: `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED`.
- `PROCESS_STATE_FINISHED` does NOT mean approved. Read the outcome in `data.humanToken.status` (`validated` when Unico recognized the person) and in `data.ndocs`, when present. This flow returns no `data.liveness` and no `data.humanTokenMatch`; those fields belong to the Journey flows, so do not branch on them.
- A process in `PROCESS_STATE_CREATED` only advances when you read it. There is no background job.
- Create is synchronous and waits for Unico. Set the HTTP client timeout to at least 60 seconds.
## Phase 1: read-only discovery
Before changing anything, inspect the repository (manifest files, HTTP client in use, config and env conventions, error handling, logging, test framework, existing Unico code). Ask the developer only for what you cannot infer:
1. The target language and framework, if not clear from the repository.
2. The Human Plugin base URL for each environment.
3. Which Attribute catalog code (`credential.type`) the product uses, or whether it creates processes without a document.
Automate: client, types, config, polling helper, tests, and a smoke test. Hand off to the developer: starting the container, setting its access key, enabling the access key for the flow, and any step that needs a real person.
## Phase 2: guardrails
Do:
- Follow the repository's structure, linter, HTTP client, and error-handling style.
- Parse responses with a JSON decoder, never with regular expressions.
- Make the base URL configurable. Do not hardcode it.
- Send the person's document only in `credential.value`. Keep documents, selfie images, `imageBase64`, and `humanToken` values out of logs.
- Treat any `4xx`/`5xx` body as data; read `message`, not the HTTP text.
Do not:
- Add an authorization header. Human Plugin does not read one.
- Put a `clientReference`, `client_id`, `correlation_id`, or any other name that is not in the field list below in the create body. Reserved names are refused with `400 INVALID_REQUEST`, and a misspelled optional field may be silently ignored.
- Expose the client to a browser, a mobile app, or a public ingress.
- Invent endpoints, headers, fields, or `credential.type` codes.
## Phase 3: prerequisites
Ask the developer to confirm before you write code (you may not be able to reach the service yourself):
- Human Plugin is running and `GET <base-url>/health/ready` answers `200`.
- The Unico access key it was started with is enabled for the flow you will use.
- The Attribute catalog (`https://human-token-assets.unico.app/attribute-catalog.json`) lists the `credential.type` you will send. Codes are case-sensitive. A type outside the catalog is refused with `422 ATTRIBUTE_TYPE_NOT_SUPPORTED` before anything is stored.
Add one environment variable, `HUMAN_PLUGIN_URL`, to the repository's config and `.env.example`, with a placeholder value. Do not name it `HUMAN_API_URL`: that name belongs to the container, where it points to the Unico API. Add no other dependency than an HTTP client the repository already uses, unless the developer agrees.
## Phase 4: implementation
### Step 1: create a process (`POST /v1/processes`, flow `api+humantoken`)
Request fields:
- `flow`: `"api+humantoken"` (required, up to 64 bytes).
- `clientId`: your client identifier, up to 128 bytes (required).
- `correlationId`: your own unique key, up to 128 bytes (required). It must be unique across all processes in every state; a reused value is refused with `409 CORRELATION_ID_ALREADY_USED`.
- `credential`: the key must be present. Send `{"type":"<catalog code>","value":"<document number, up to 64 bytes>"}`, or `null`, or `{}` when there is no document. Do not send `type` or `value` as empty strings, and send no other keys.
- `imageBase64`: the selfie as base64, PNG, JPEG, or WebP, up to 800 KB. Use a frontal, well-lit selfie of one face.
Rules: `flow`, `clientId`, and `correlationId` must not contain control characters or leading or trailing whitespace; invalid values are rejected, not rewritten. The body is one JSON object of at most 2 MiB.
```bash
curl -sS -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
-H "Content-Type: application/json" \
-d '{
"flow": "api+humantoken",
"clientId": "client-a",
"correlationId": "onboarding-001",
"credential": { "type": "<catalog-code>", "value": "<document-number>" },
"imageBase64": "<base64-selfie>"
}' -i
```
Before each call, record the attempt, keyed by `correlationId`, in a store the repository already has. If it has none, ask the developer before adding one. Keep the `id` from the response: Human Plugin cannot look a process up by `correlationId`, so a lost `id` cannot be recovered.
### Step 2: read the process until it is final (`GET /v1/processes/{id}`)
In the `api+humantoken` flow the create answer is already final, so one read confirms it. Implement a bounded helper anyway: read, stop on `PROCESS_STATE_FINISHED` or `PROCESS_STATE_FAILED`, and keep going on `PROCESS_STATE_CREATED` with a delay and a maximum number of attempts. Retry a read on `502`, `503` or a network error, and stop on `404`. Once the process is final, save its outcome in the same store and do not read it again: every read of a finished process adds a row to Human Plugin's audit table, which is never pruned.
Decision table for the caller:
| State | Final? | What to do |
| :--- | :--- | :--- |
| `PROCESS_STATE_CREATED` | No | Read again after a delay, up to your limit. |
| `PROCESS_STATE_FINISHED` | Yes | Apply your business rule to `data.humanToken.status` and, when present, `data.ndocs`. Do not read FINISHED as approval. |
| `PROCESS_STATE_FAILED` | Yes | `data` is empty. Create a new process with a new `correlationId` if the business wants a retry. |
`data.ndocs` can be absent. When present it holds `distinctClientsCount`, `transactionsCount`, `firstSeen`, `lastSeen`, and `credentials[]`. Handle it as optional.
### Step 3: fetch the selfie when needed (`GET /v1/processes/{id}/selfie`)
Do this only if the product must keep the captured selfie. Human Plugin does not store it, and it is only available for a limited time after the process finishes, so store it right away if you need it. Treat the image as biometric data.
```bash
curl -sS "$HUMAN_PLUGIN_URL/v1/processes/$PROCESS_ID/selfie" | jq -r .fileContents | base64 -d > selfie.img
```
Choose the file extension from the `contentType` in the response (`image/jpeg` is the documented example).
### Step 4: error handling
Implement exactly this matrix.
| Call | Response | Cause | Action |
| :--- | :--- | :--- | :--- |
| Create | `400` `INVALID_REQUEST`, `REQUEST_TOO_LARGE`, `MISSING_<FIELD>`, `INVALID_<FIELD>` | Body is invalid | Fix the request. Do not retry. |
| Create | `400` `INVALID_IMAGE` (not valid base64), `400` `IMAGE_TOO_LARGE` (over 800 KB), or `400` `UNSUPPORTED_IMAGE_FORMAT` (not PNG, JPEG, or WebP) | The image was refused | Fix the image. The process is stored as failed and the `correlationId` is used up, so retry with a NEW `correlationId`. |
| Create | `409` `DUPLICATE_IMAGE` | The same image was used recently | Capture a new image. The `correlationId` is used up, so retry with a NEW `correlationId`. |
| Create | `401` with an empty message | Unico refused the access key | The process is stored as failed. Stop and tell the developer to check the access key the container runs with. After the fix, use a NEW `correlationId`. |
| Create | `403` `PERMISSION_DENIED` | Access key not enabled for the flow | The process is stored as failed. Stop and tell the developer. After the fix, use a NEW `correlationId`. |
| Create | `409` `CORRELATION_ID_ALREADY_USED` | Key reused | Read the existing process if you kept its `id`. Otherwise use a new `correlationId`. |
| Create | `422` `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` is not in the catalog | Fix the code. Do not retry. |
| Create | `503` `DATABASE_UNAVAILABLE` | Unico was not called, but the process may already be stored | Retry with backoff and the SAME `correlationId`. If the retry answers `409` `CORRELATION_ID_ALREADY_USED`, create again with a NEW `correlationId`. |
| Create | `502` `UPSTREAM_UNAVAILABLE` or `500` `INTERNAL` | The outcome is uncertain | Do NOT retry automatically. The process may be stored as failed. A new create needs a NEW `correlationId`; let a business rule decide. |
| Read or selfie | `404` `PROCESS_NOT_FOUND` or `SELFIE_NOT_FOUND` | Unknown or deleted id, or no selfie | Do not retry. |
| Read or selfie | `502`, `503` or a network error | Temporary problem | Retry with backoff and a limit. |
| Selfie | `401` | Unico refused the access key | Stop and tell the developer. |
| Any | `500` `INTERNAL` | Unexpected failure | Log the `message` without PII and surface it. On create, apply the `502`/`500` rule above. |
Human Plugin has no built-in rate limiter, so do not expect `429`. If the product needs a limit, apply it in your own code or gateway.
## Phase 5: verification
1. Run the repository's build, lint, and test commands. Add unit tests with a mocked HTTP layer for: successful create, each row of the error matrix, `PROCESS_STATE_CREATED` followed by `PROCESS_STATE_FINISHED`, an absent `data.ndocs`, and a reused `correlationId`.
2. Ask the developer for a non-production base URL. If you cannot reach it, say so and do not claim readiness. Otherwise run `GET /health/ready`. A real create stores a process, uses up a `correlationId`, and counts toward the installation's `ndocs` figures, so run one only against that non-production URL, with test data the developer provides. Do not invent a selfie or a document.
3. Search the diff for secrets, real documents, base64 selfies, and `humanToken` values in logs or fixtures.
## Phase 6: definition of done
You are done only when all of this is true:
- The client covers create, read, and selfie, and the base URL comes from configuration.
- No authorization header is sent and no `credential` value is logged.
- The retry rules match the Step 4 matrix, including never auto-retrying a `502` or `500` on create.
- `FINISHED` is not treated as approved.
- Tests pass, and the leak search found nothing.
- The report below was delivered.
## Phase 7: final report
End with:
1. The files created or changed, one line each.
2. The commands you ran and their real results. Mark anything you could not run as "not run" and say why.
3. What the developer must still do: start Human Plugin with the access key Unico gave you (`HUMAN_API_ACCESS_KEY`) and its database, confirm with Unico that the key is enabled for the `api+humantoken` flow, and run one real create against a non-production Human Plugin with a selfie and a document the developer provides, because an agent has neither.
Le résultat de l'agent ne vaut que ce que valent les faits ci-dessus. Lorsqu'il a besoin de plus de détails, orientez-le vers Créer un processus, Obtenir un processus, Obtenir le selfie, Erreurs et nouvelles tentatives et Dépannage.