Skip to content

edit documentation for the js package to add session proofs vs request documentation - #320

Open
kchaw2005 wants to merge 38 commits into
mainfrom
kartike/add-session-doc
Open

kchaw2005 wants to merge 38 commits into
mainfrom
kartike/add-session-doc

Conversation

@kchaw2005

@kchaw2005 kchaw2005 commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

What

edited the readme in js/packages/core

  • added documentation for how to create session proof requests via IDKit.createSession and how that's different than requests created via IDKit.request
  • mentioned that sessions don't require an action key

Why

the js core package is our most used entrypoint into world ID. The migration documentation from v3.0 to v4.0 is a little unfinished / messy, as parallel documentation exists for legacy proof creation flows and v4.0 in the docs but not necessarily in this github


Note

Low Risk
README-only changes with no runtime, API, or security behavior modifications.

Overview
Documentation-only updates to @worldcoin/idkit-core and @worldcoin/idkit READMEs to clarify v4 integration paths and align examples with current APIs.

Both packages get a Quickstart that splits session-scoped proofs (createSession / proveSession or IDKitSessionWidget + existing_session_id) from action-scoped requests (IDKit.request / IDKitRequestWidget with action, nullifier handling, and backend verify). Examples now pass rp_context straight from the backend instead of hand-assembling fields, document CredentialRequest / .constraints() as the default v4 path, and call out backend verification via /api/v4/verify/{rp_id}.

Core README also reframes RP signing (optional action for sessions), consolidates preset/legacy guidance (sessions don’t use presets), trims duplicate verify snippets, and drops the “zero dependencies, WASM-powered” tagline. React README de-emphasizes headless hooks in highlights, mirrors the session vs request widget flows, and adds IDKitInviteCodeRequestWidget for cross-device use.

Reviewed by Cursor Bugbot for commit 2c2ce41. Bugbot is set up for automated code reviews on this repo. Configure here.

@vercel

vercel Bot commented Aug 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
idkit-js-example Ready Ready Preview Sep 24, 2026 11:55pm UTC

Request Review

@kchaw2005 kchaw2005 changed the title first readme change edit documentation for the js package to add session proofs vs request documentation Aug 13, 2026
kchaw2005 and others added 7 commits September 2, 2026 14:40
Removed mention of session constraints in the proof request section.
Removed section on handling the result in the backend, including example code for verifying proof.
Removed backend RP signature generation section and related examples from the README.
@kchaw2005

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 2, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-02T22:52:55.281296Z 255db6a Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 255db6a8df

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

```tsx
import { useIDKitSession, CredentialRequest } from "@worldcoin/idkit";

const rp_context = await fetch("/api/rp-signature").then((r) => r.json());

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Fetch a fresh RP context for each hook attempt

This module-level fetch reuses one nonce and signature for every flow.open() during the page lifetime; the request example repeats the same pattern. Since signRequest defaults to a five-minute TTL and the nonce is single-use, a user who waits before clicking or retries after a reset will receive rp_signature_expired or duplicate_nonce. Generate a new rp_context for each attempt rather than once when the module loads.

Useful? React with 👍 / 👎.

Remove comment about fresh rp_context for request creation.
Comment thread js/packages/react/README.md Outdated
const rp_context = await fetch("/api/rp-signature").then((r) => r.json());

function CreateSessionExample() {
const flow = useIDKitSession({

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RPs should default to using the react widgets; otherwise they should use the js core library

Kartike Chawla and others added 3 commits September 2, 2026 16:23

This branch was successfully deployed

1 active deployment
Preview — 2c2ce41c Deployed Sep 24, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants