Skip to content

🔖 Version 4.7.0-rc1 #195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 13, 2025
Merged

🔖 Version 4.7.0-rc1 #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Mindee Ruby API Library Changelog

## v4.7.0-rc1 - 2025-08-13
### Changes
* :sparkles: add support for client V2 & associated features

### Fixes
* :recycle: add many missing internal types
* :bug: fix invalid types for many V1 features
* :bug: fix V1 errors sometimes having the wrong code
* :bug: fix many presumably immutable fields having non-readonly parameters
* :bug: fix broken `resources` accessor in `ApiRequest` object


## v4.6.0 - 2025-06-03
### Changes
* :sparkles: add support for address fields
Expand Down
243 changes: 21 additions & 222 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,240 +4,39 @@

Quickly and easily connect to Mindee's API services using Ruby.

## Requirements
## Mindee API Versions
This client library has support for both Mindee platform versions.

The following Ruby versions are tested and supported: 3.0, 3.1, 3.2, 3.3, 3.4
### Latest - V2
This is the new platform located here:

## Quick Start
https://app.mindee.com

Here's the TL;DR of getting started.
It uses **API version 2**.

First, get an [API Key](https://developers.mindee.com/docs/create-api-key)
Consult the
**[Latest Documentation](https://docs.mindee.com/integrations/client-libraries-sdk)**

Install by adding this line to your application's Gemfile:

```ruby
gem 'mindee'
```
### Legacy - V1
This is the legacy platform located here:

And then execute:
https://platform.mindee.com/

```sh
bundle install
```
It uses **API version 1**.

Finally, Ruby away!
Consult the
**[Legacy Documentation](https://developers.mindee.com/docs/ruby-getting-started)**

### Environment Variables
## Additional Information

This library offers customizable features through environment variables. While there may be instances where you need to
rely on them, it's crucial to exercise caution when modifying them to avoid unintended consequences.
**[Source Code](https://github.com/mindee/mindee-api-ruby)**

If you're unsure whether you need to adjust these variables, it's advisable to refrain from doing so unless you have a
specific reason. Accidentally overwriting them can lead to unexpected behavior.
**[Reference Documentation](https://mindee.github.io/mindee-api-ruby/)**

Before making any changes, we recommend reviewing the following information to understand the purpose and potential
impact of each environment variable:
**[Feedback](https://feedback.mindee.com/)**

* `MINDEE_API_KEY`:
* **Description**: Your personal Mindee API Key as shown on the platform. Be careful not to show this publicly!
* **Default Value**: `nil`
* `MINDEE_BASE_URL`:
* **Description**: The default base URL of the API endpoint. Use this variable to specify the root URL for API requests. Modify as needed for proxy configurations or changes in API endpoint location.
* **Default Value**: `https://api.mindee.net/v1`
* `MINDEE_REQUEST_TIMEOUT`:
* **Description**: The default timeout for HTTP requests (in seconds).
* **Default Value**: `120`
* `MINDEE_LOG_LEVEL`:
* **Description**: The default logging level for the mindee logger.
* **Default Value**: `WARN`
### License
Copyright © Mindee

### Loading a File and Parsing It

#### Global Documents

```ruby
require 'mindee'

# Init a new client
mindee_client = Mindee::Client.new(api_key: 'my-api-key')

# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')
result = mindee_client.parse(
input_source,
Mindee::Product::Invoice::InvoiceV4
)

# Print a full summary of the parsed data in RST format
puts result.document
```

**Note:** Files can also be loaded from:

A URL (`https`):

```rb
input_source = mindee_client.source_from_url("https://my-url")
```

A bytes input stream:

```rb
input_source = mindee_client.source_from_bytes('/path/to/the/file.ext', "name-of-my-file.ext")
```

A base64 encoded string:

```rb
input_source = mindee_client.source_from_b64string('/path/to/the/file.ext', "name-of-my-file.ext")
```

A ruby `file` object:

```rb
input_source = mindee_client.source_from_file(input_file, "name-of-my-file.ext")
```

#### Region-Specific Documents

```ruby
require 'mindee'

# Init a new client
mindee_client = Mindee::Client.new(api_key: 'my-api-key')

# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')

result = mindee_client.parse(
input_source,
Mindee::Product::EU::LicensePlate::LicensePlateV1
)

# Print a full summary of the parsed data in RST format
puts result.document
```

### Universal - All Other Documents

The Universal product acts as a catch-all for every and any API if it doesn't have an assigned product name.

```ruby
require 'mindee'

# Init a new client and configure your custom document
mindee_client = Mindee::Client.new(api_key: 'my-api-key')
endpoint = mindee_client.create_endpoint(
endpoint_name: 'my-endpoint',
account_name: 'my-account'
)

# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')

result = mindee_client.parse(
input_source,
Mindee::Product::Universal::Universal,
endpoint: endpoint
)

# Print a full summary of the parsed data in RST format
puts result.document

# Looping over all prediction values
result.document.inference.prediction.fields.each do |field_name, field_data|
puts field_name
puts field_data.values
puts field_data.to_s
end
```


## Enqueueing and Parse a Webhook Response

This is an optional way of handling asynchronous APIs.

```rb
require 'mindee'

# Init a new client
mindee_client = Mindee::Client.new(api_key: 'my-api-key')

# Load a file from disk
input_source = mindee_client.source_from_path('/path/to/the/file.ext')


# Send the file to the server
enqueue_response = mindee_client.enqueue(
input_source,
Mindee::Product::InternationalId::InternationalIdV2
)

job_id = enqueue_response.job.id

# Load the JSON string sent by the Mindee webhook POST callback.
# Reading the callback data will vary greatly depending on your HTTP server.
# This is therefore beyond the scope of this example.

local_response = Mindee::Input::LocalResponse.new(request.body.string)

# You can also use a File object as the input.
# FILE_PATH = File.join('path', 'to', 'file.json').freeze
# local_response = Mindee::Input::LocalResponse.new(FILE_PATH);

# Optional: verify the HMAC signature.
unless local_response.valid_hmac_signature?(my_secret_key, 'invalid signature')
raise "Invalid HMAC signature!"
end


# Deserialize the response:
result = mindee_client.load_prediction(
Mindee::Product::InternationalId::InternationalIdV2,
local_response
)

# Print a full summary of the parsed data in RST format
puts result.document
```


## CLI Tool

A command-line interface tool is available to quickly test documents:

```sh
ruby ./bin/mindee.rb <product_name> path/to/your/file.ext
```

Using the ruby bundler:

```sh
bundle exec ruby ./bin/mindee.rb <product_name> path/to/your/file.ext
```

Where possible values for `<product_name>` can be displayed by running the command with no arguments.

## Further Reading

There's more to it than that for those that need more features, or want to
customize the experience.

* [Ruby Overview](https://developers.mindee.com/docs/ruby-getting-started)
* [Common file operations](https://developers.mindee.com/docs/ruby-common-file-operations)
* [Global products](https://developers.mindee.com/docs/ruby-global-products)
* [Localized products](https://developers.mindee.com/docs/ruby-localized-products)

You can also take a look at the
[Reference Documentation](https://mindee.github.io/mindee-api-ruby/).

## License

Copyright © Mindee, SA

Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Questions?

[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)
Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
2 changes: 1 addition & 1 deletion lib/mindee/version.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Mindee
module Mindee
# Current version.
VERSION = '4.6.0'
VERSION = '4.7.0-rc1'

# Finds and return the current platform.
# @return [Symbol, Hash[String | Symbol, Regexp], Nil?]
Expand Down
Loading