https://github.com/treedomtrees/opa-client-sdk
An undici-based client for Open Policy Agent
https://github.com/treedomtrees/opa-client-sdk
Last synced: 10 months ago
JSON representation
An undici-based client for Open Policy Agent
- Host: GitHub
- URL: https://github.com/treedomtrees/opa-client-sdk
- Owner: treedomtrees
- License: mit
- Created: 2024-09-04T13:24:01.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-20T07:10:53.000Z (over 1 year ago)
- Last Synced: 2025-08-08T23:27:31.475Z (10 months ago)
- Language: TypeScript
- Size: 143 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# @treedom/opa-client-sdk
An undici-based client for [Open Policy Agent](https://www.openpolicyagent.org/).
__Made with ❤️ at [
](#-join-us-in-making-a-difference-)__, [join us in making a difference](#-join-us-in-making-a-difference-)!
## Install
```bash
npm install @treedom/opa-client-sdk
```
## Quickstart
```ts
import { OpenPolicyAgentClient } from '@treedom/opa-client-sdk';
import { LRUCache } from 'lru-cache'
const cache = new LRUCache();
const opaClient = new OpenPolicyAgentClient({
url: 'https://my-opa.example.com',
cache?: Cache // optional
opaVersion?: string // defaults to 'v1'
method?: 'POST' | 'GET' // defaults to 'POST'
requestOptions?: UndiciRequestOptions // among other things, allows setting a proxy
})
```
## Usage
The `OpenPolicyAgentClient` class provides three methods: `evaluate`, `assert`, and `query`.
- All methods take the policy name and input as arguments. When specified, the input is expected to be an object.
- All the keys in the input object are optional; some frequently used keys, like `subject`, `resource`, and `headers`, are typed for convenience in `OpaQueryInput`.
- All the methods support generic types allowing customization when needed.
- Using the provided configuration, the client will make a request to the OPA server on `/{opaVersion}/data/{policyName}`.
#### Evaluate
The `evaluate` method returns the result of the policy evaluation. Throws only when the evaluation fails, following a network error for example. The policy is expected to return an object with a `result` key: `{ result: boolean }`.
```ts
await opaClient.evaluate(
'data.my.policy.package', // Policy name
{ // Input
subject: {
id: '123',
type: 'user'
},
resource: {
id: '456',
type: 'document'
},
headers: {
authorization: 'Bearer token'
}
}
) // Returns a boolean
```
#### Assert
The `assert` method throws an error if the response does not match the expected value.
```ts
await opaClient.assert(
'data.my.policy.package', // Policy name
{ // Input
subject: {
id: '123',
type: 'user'
},
resource: {
id: '456',
type: 'document'
},
headers: {
authorization: 'Bearer token'
}
},
true // Expected value
) // Returns void
```
#### Query
The `query` method makes a direct call to the OPA server and returns the raw body, or throws an error if the query fails (status code different from 200).
```ts
const { result } = await opaClient.query(
'data.my.policy.package', // Policy name
{ // Input
subject: {
id: '123',
type: 'user'
},
resource: {
id: '456',
type: 'document'
},
headers: {
authorization: 'Bearer token'
}
}
) // Returns an object
```
## 🌳 Join Us in Making a Difference! 🌳
We invite all developers who use Treedom's open-source code to support our mission of sustainability by planting a tree with us. By contributing to reforestation efforts, you help create a healthier planet and give back to the environment. Visit our [Treedom Open Source Forest](https://www.treedom.net/en/organization/treedom/event/treedom-open-source) to plant your tree today and join our community of eco-conscious developers.
Additionally, you can integrate the Treedom GitHub badge into your repository to showcase the number of trees in your Treedom forest and encourage others to plant new ones. Check out our [integration guide](https://github.com/treedomtrees/.github/blob/main/TREEDOM_BADGE.md) to get started.
Together, we can make a lasting impact! 🌍💚
## Contributing
Contributions are welcome! Please read the contributing guidelines before submitting a pull request.
## License
This project is licensed under the MIT License.