Vision API React client 1.0.0

Author: herle88

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # 18.17 is the floor the package declares; test the ends of the range.
+        node: ['18', '20', '22', '24']
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm install
+      - run: npm run typecheck
+      # The suite stubs `fetch`, so it needs no API key and makes no network calls.
+      - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v[0-9]+.[0-9]+.[0-9]+']
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write # OIDC — trusted publishing and provenance both need this
+    env:
+      # Bootstrap only. npm cannot configure a trusted publisher for a package that does not
+      # exist yet (npm/cli#8544), so 1.0.0 goes out under a short-lived granular token. Once
+      # the trusted publisher is configured, delete this secret: with it absent the auth step
+      # below is skipped and the job authenticates entirely over OIDC.
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+          # Deliberately no `registry-url:`. It writes `_authToken=${NODE_AUTH_TOKEN}` into
+          # ~/.npmrc; with that variable unset npm sees the unexpanded placeholder, decides
+          # auth is already configured, never starts the OIDC exchange, and fails ENEEDAUTH.
+          # See actions/setup-node#1551. registry.npmjs.org is npm's default anyway.
+
+      - name: Use an npm that can do trusted publishing
+        run: npm install -g npm@latest # trusted publishing needs npm >= 11.5.1
+
+      - name: Tag must match package.json
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(node -p "require('./package.json').version")"
+          [ "$tag" = "$pkg" ] || { echo "tag $tag != package.json $pkg"; exit 1; }
+
+      - run: npm ci
+      - run: npm run typecheck
+      # The suite stubs `fetch`, so it needs no API key and makes no network calls.
+      - run: npm test
+
+      - name: Bootstrap auth (skipped once NPM_TOKEN is deleted)
+        if: env.NPM_TOKEN != ''
+        run: printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" >> "$HOME/.npmrc"
+
+      - name: Publish
+        # `prepublishOnly` runs the build, so dist/ is fresh. --provenance is required when
+        # publishing with a token and redundant but harmless under trusted publishing, which
+        # emits provenance on its own.
+        run: npm publish --access public --provenance

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.*
+.DS_Store
+npm-debug.log*
+coverage/

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package follows
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-08-09
+
+First public release.
+
+- `useAnalyze`, `useAsk`, `useDetect` — one file in, structured JSON out, with upload
+  progress, cancellation and unmount safety
+- `useTask` — polls an async task until it settles, and stops on its own
+- `usePresets` — the catalog, for a picker
+- `VisionProvider` for the endpoint base path and headers, with per-hook overrides
+- `VisionError` with `code`, the convenience flags, and a `userMessage` you can render
+- `unwrap` / `value` / `rows` / `belowConfidence` result helpers
+- Built for the backend-proxy pattern: the hooks talk to your endpoint, never to the API
+  directly, because an API key is a live spending credential

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Thanks for taking the time. Issues and pull requests are welcome at
+<https://github.com/devrobotlabs/visionapi-react>.
+
+If your question is about the **API itself** — a preset, a credit cost, a limit, an error
+code — <https://support.visionapi.io> reaches the team faster than an issue here does. This
+repository is the React client; the service it talks to is documented at
+<https://docs.visionapi.io>.
+
+## Getting set up
+
+```bash
+git clone https://github.com/devrobotlabs/visionapi-react.git
+cd visionapi-react
+npm install
+```
+
+## Before you open a pull request
+
+Run what CI runs:
+
+```bash
+npm run typecheck
+npm test
+```
+
+The test suite stubs the transport, so it needs **no API key and makes no network calls**.
+A test that reaches the real API will not be merged — it makes the suite slow, flaky, and
+impossible to run on a fork.
+
+This package never talks to the API directly. If a change makes it hold an API key in the browser, it is the wrong change — see the README's proxy examples for the shape that is correct.
+
+## One contract, nine libraries
+
+This is one of nine clients — Node, Python, Go, Ruby, PHP, Java, Swift, React and Vue — that
+deliberately expose the same surface, named the way each language names things. A change to
+behaviour rather than to style is usually a change all nine need, so say so in the pull
+request and we will sort out the rest of the set.
+
+Three rules the libraries exist to get right, and which any change has to preserve:
+
+- **Every scalar is wrapped** in `{value, confidence}`, and a line-item array is a *bare*
+  array whose cells are wrapped individually — not a wrapped array of plain values.
+- **Absent is not missing.** A preset response contains every field of the preset, with the
+  ones the document did not carry as `value: null`. Do not drop them.
+- **Retries cannot double-charge.** Every billable POST carries a generated
+  `Idempotency-Key`; 429 honours the server's `Retry-After`, and 402 and input errors are
+  never retried because they cannot succeed.
+
+## Style
+
+Match the surrounding code. The linters listed above are the arbiter for everything they
+cover; for everything else, the existing files are.
+
+## Reporting a security issue
+
+Please do not open a public issue — see [SECURITY.md](./SECURITY.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vision API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.