bizowie-api 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd5c5425932023526bd9d2f1a1c52907686d3b42a5aa1c9e610950d50ebd037c
+  data.tar.gz: 5e9d369dff684e4fc65a260881940b1be5366df1c1e5991dfcf95a37eeda50dc
+SHA512:
+  metadata.gz: d67e5d2553436eb96c92eeacf03beed406298e0d9f1945ac1e4b97b644adeb50b77e2cd25518fd805c1fe9ec5371aeb6ffaf6ade5f7f0cdd6a903d9f0f6ff85d
+  data.tar.gz: a44c36b0dd2fdee3182cfe0b68d92e0fa665b482ae441859668da17e7e1b865154b37d6aacd9b52eaa036bc5a730384f1bafb6a07b46c34296206ee55a827552

data/README.md

@@ -0,0 +1,126 @@
+# bizowie-api (Ruby)
+
+Ruby client for [Bizowie's](https://bizowie.com) ERP API. Port of the Perl
+[`WWW::Bizowie::API`](https://github.com/bizowie/WWW-Bizowie-API) module.
+
+- Zero runtime dependencies (only Ruby stdlib: `net/http`, `json`)
+- Supports both the v1 and v2 API endpoints
+
+## Requirements
+
+- Ruby **2.7 or newer**
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'bizowie-api'
+```
+
+Or install directly:
+
+```bash
+gem install bizowie-api
+```
+
+## Quick start
+
+```ruby
+require 'bizowie/api'
+
+bz = Bizowie::API.new(
+  api_key:    '02cc7058-cd22-4c8e-ad7c-a8f3f2a64bd0',
+  secret_key: '58c57abc-1e16-3571-bb35-73876bcef746',
+  site:       'mysite.bizowie.com',
+  v2:         true, # recommended for new integrations
+)
+
+res = bz.call('databases/add_note/3/10/123', comment: 'hello from Ruby')
+
+if res.success == 1
+  puts "ok: #{res.data.inspect}"
+else
+  warn "failed: #{res.data.inspect}"
+end
+```
+
+## API
+
+### `Bizowie::API.new(**options)`
+
+Creates a client instance. Raises `ArgumentError` if `site`, `api_key`, or
+`secret_key` is missing.
+
+| Option        | Type      | Required | Description                                                                   |
+| ------------- | --------- | -------- | ----------------------------------------------------------------------------- |
+| `api_key`     | `String`  | yes      | Your Bizowie API key.                                                         |
+| `secret_key`  | `String`  | yes      | Your Bizowie secret key.                                                      |
+| `site`        | `String`  | yes      | Hostname of your Bizowie instance (e.g. `mysite.bizowie.com`).                |
+| `v2`          | `Boolean` | no       | Route calls through the v2 endpoint (`/bz/apiv2/call/`). Recommended.         |
+| `api_version` | `String`  | no       | API version sent with each v2 request. Defaults to `'1.00'`.                  |
+| `debug`       | `Boolean` | no       | Log the raw HTTP body to stderr when the response can't be parsed as JSON.    |
+
+### `client.call(method, params = nil)` → `Bizowie::API::Response`
+
+Makes an API call.
+
+- `method` — path to the API method (everything after `/bz/api/` for v1 or
+  `/bz/apiv2/call/` for v2). Raises if empty.
+- `params` — `Hash` of parameters; JSON-encoded for you. May be omitted.
+
+In v2 mode, `api_key`, `secret_key`, and `api_version` are injected
+automatically — don't include them in `params`.
+
+### `Bizowie::API::Response`
+
+| Method    | Returns   | Description                                                                                                   |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| `success` | `Integer` | `1` on success, `0` otherwise. Pulled from the response body's `success` field.                               |
+| `data`    | `Hash`    | Decoded JSON response (with `success` removed). On a non-JSON response this is `{ 'unprocessed' => 1 }`.      |
+
+## Error handling
+
+`call` does **not** raise on HTTP errors — application-level failures are
+surfaced via `success: 0` and whatever the server returned in `data`. It
+*does* raise on network-level failures (DNS, connection refused, TLS
+errors), since those bubble up from `Net::HTTP`. Rescue if you want to
+handle those distinctly:
+
+```ruby
+begin
+  res = bz.call('some/method', foo: 'bar')
+  warn 'application-level failure' unless res.success == 1
+rescue StandardError => e
+  warn "network/TLS failure: #{e.message}"
+end
+```
+
+If the server returns non-JSON (e.g., an HTML error page), `res.success`
+will be `0` and `res.data` will be `{ 'unprocessed' => 1 }`. Pass
+`debug: true` to the constructor to log the raw body to stderr while
+wiring things up.
+
+## v1 vs v2
+
+| Aspect          | v1 (default)                               | v2 (`v2: true`)                                  |
+| --------------- | ------------------------------------------ | ------------------------------------------------ |
+| Endpoint        | `https://{site}/bz/api/{method}`           | `https://{site}/bz/apiv2/call/{method}`          |
+| Auth            | Sent as separate multipart form fields     | Injected into the JSON request body              |
+| Body            | `multipart/form-data` with a `request` JSON field | Raw JSON body with `Content-Type: form-data` |
+| `api_version`   | not sent                                   | sent (defaults to `'1.00'`)                      |
+
+v2 is recommended for new integrations.
+
+## TLS verification
+
+Unlike the Perl module, this client **does not disable TLS verification**.
+If you need to talk to a host with a self-signed certificate (e.g., a dev
+instance), the cleanest approach is to install the cert into your trust
+store rather than to disable verification.
+
+## License
+
+Dual-licensed under the
+[Artistic License 1.0](https://opensource.org/licenses/Artistic-1.0) or the
+GPL 1.0+, matching the original Perl module.

data/bizowie-api.gemspec

@@ -0,0 +1,25 @@
+require_relative 'lib/bizowie/api/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'bizowie-api'
+  spec.version     = Bizowie::API::VERSION
+  spec.authors     = ['Bizowie']
+  spec.email       = ['info@bizowie.com']
+
+  spec.summary     = "Ruby client for Bizowie's ERP API."
+  spec.description = 'Ruby port of WWW::Bizowie::API. Provides a simple ' \
+                     'client for the v1 and v2 Bizowie ERP API endpoints.'
+  spec.homepage    = 'https://bizowie.com'
+  spec.licenses    = ['Artistic-1.0-Perl', 'GPL-1.0-or-later']
+
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.files = Dir['lib/**/*.rb'] + %w[README.md bizowie-api.gemspec]
+  spec.require_paths = ['lib']
+
+  spec.metadata = {
+    'homepage_uri'    => 'https://bizowie.com',
+    'source_code_uri' => 'https://github.com/bizowie/WWW-Bizowie-API',
+    'bug_tracker_uri' => 'https://github.com/bizowie/WWW-Bizowie-API/issues',
+  }
+end

data/lib/bizowie/api/response.rb

@@ -0,0 +1,19 @@
+module Bizowie
+  class API
+    # Response returned by {Bizowie::API#call}.
+    #
+    # @!attribute [r] data
+    #   @return [Hash] Decoded JSON response body (with +success+ removed).
+    #     +{ 'unprocessed' => 1 }+ if the body could not be parsed.
+    # @!attribute [r] success
+    #   @return [Integer] +1+ on success, +0+ otherwise.
+    class Response
+      attr_reader :data, :success
+
+      def initialize(data:, success:)
+        @data = data
+        @success = success
+      end
+    end
+  end
+end

data/lib/bizowie/api/version.rb

@@ -0,0 +1,5 @@
+module Bizowie
+  class API
+    VERSION = '0.5.0'.freeze
+  end
+end

data/lib/bizowie/api.rb

@@ -0,0 +1,142 @@
+require 'json'
+require 'net/http'
+require 'securerandom'
+require 'uri'
+
+require_relative 'api/response'
+require_relative 'api/version'
+
+module Bizowie
+  # Ruby client for the Bizowie ERP API.
+  #
+  # @example
+  #   require 'bizowie/api'
+  #
+  #   bz = Bizowie::API.new(
+  #     api_key:    '02cc7058-cd22-4c8e-ad7c-a8f3f2a64bd0',
+  #     secret_key: '58c57abc-1e16-3571-bb35-73876bcef746',
+  #     site:       'mysite.bizowie.com',
+  #     v2:         true,
+  #   )
+  #
+  #   res = bz.call('databases/add_note/3/10/123', comment: 'hello from Ruby')
+  #   puts res.success
+  #   puts res.data
+  class API
+    USER_AGENT = 'Bizowie::API'.freeze
+
+    # @param api_key     [String] Your Bizowie API key.
+    # @param secret_key  [String] Your Bizowie secret key.
+    # @param site        [String] Hostname of your Bizowie instance (e.g. +mysite.bizowie.com+).
+    # @param v2          [Boolean] Route calls through the v2 endpoint. Recommended for new integrations.
+    # @param api_version [String, nil] API version sent with each v2 request. Defaults to +'1.00'+.
+    # @param debug       [Boolean] When true, log the raw HTTP body to stderr if the response can't be parsed as JSON.
+    # @raise [ArgumentError] if +site+, +api_key+, or +secret_key+ is missing.
+    def initialize(api_key:, secret_key:, site:, v2: false, api_version: nil, debug: false)
+      raise ArgumentError, 'site not specified'       if site.nil?       || site.to_s.empty?
+      raise ArgumentError, 'api_key not specified'    if api_key.nil?    || api_key.to_s.empty?
+      raise ArgumentError, 'secret_key not specified' if secret_key.nil? || secret_key.to_s.empty?
+
+      @api_key     = api_key
+      @secret_key  = secret_key
+      @site        = site
+      @v2          = v2
+      @api_version = api_version
+      @debug       = debug
+    end
+
+    # Make an API call. Dispatches to the v1 or v2 endpoint based on the
+    # +v2+ option passed to the constructor.
+    #
+    # Does not raise on HTTP errors — application-level failures are surfaced
+    # via +success: 0+ on the returned response. Network-level failures (DNS,
+    # connection refused, TLS errors) bubble up from Net::HTTP.
+    #
+    # @param method [String] Path to the API method (everything after
+    #   +/bz/api/+ for v1 or +/bz/apiv2/call/+ for v2).
+    # @param params [Hash, nil] Parameters to send. JSON-encoded for you.
+    #   In v2 mode, +api_key+/+secret_key+/+api_version+ are injected
+    #   automatically — don't include them here.
+    # @return [Bizowie::API::Response]
+    # @raise [RuntimeError] if +method+ is empty.
+    def call(method, params = nil)
+      @v2 ? call_v2(method, params) : call_v1(method, params)
+    end
+
+    private
+
+    def call_v1(method, params)
+      raise '[Bizowie::API] fatal error: no method given' if method.nil? || method.to_s.empty?
+
+      request_body = JSON.generate(params || {})
+      boundary = "----BizowieAPI#{SecureRandom.hex(16)}"
+      body = build_multipart(boundary,
+        'api_key'    => @api_key,
+        'secret_key' => @secret_key,
+        'site'       => @site,
+        'request'    => request_body,
+      )
+
+      response = http_post(
+        "https://#{@site}/bz/api/#{method}",
+        body,
+        'Content-Type' => "multipart/form-data; boundary=#{boundary}",
+      )
+
+      parse_response(response)
+    end
+
+    def call_v2(method, params)
+      raise '[Bizowie::API] fatal error: no method given' if method.nil? || method.to_s.empty?
+
+      payload = (params || {}).each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      payload['api_key']     = @api_key
+      payload['secret_key']  = @secret_key
+      payload['api_version'] = @api_version || '1.00' unless payload['api_version']
+
+      response = http_post(
+        "https://#{@site}/bz/apiv2/call/#{method}",
+        JSON.generate(payload),
+        'Content-Type' => 'form-data',
+      )
+
+      parse_response(response)
+    end
+
+    def http_post(url, body, headers)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      headers.each { |k, v| request[k] = v }
+      request['User-Agent'] = USER_AGENT
+      request.body = body
+
+      http.request(request)
+    end
+
+    def build_multipart(boundary, fields)
+      parts = fields.map do |name, value|
+        "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n" \
+        "#{value}\r\n"
+      end
+      parts.join + "--#{boundary}--\r\n"
+    end
+
+    def parse_response(response)
+      body = response.body.to_s
+      data =
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          warn "[Bizowie::API] #{response.code} #{response.message}\n#{body}" if @debug
+          { 'unprocessed' => 1 }
+        end
+
+      success = data.delete('success') || 0
+      Response.new(data: data, success: success)
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: bizowie-api
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Bizowie
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-18 00:00:00.000000000 Z
+dependencies: []
+description: Ruby port of WWW::Bizowie::API. Provides a simple client for the v1 and
+  v2 Bizowie ERP API endpoints.
+email:
+- info@bizowie.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bizowie-api.gemspec
+- lib/bizowie/api.rb
+- lib/bizowie/api/response.rb
+- lib/bizowie/api/version.rb
+homepage: https://bizowie.com
+licenses:
+- Artistic-1.0-Perl
+- GPL-1.0-or-later
+metadata:
+  homepage_uri: https://bizowie.com
+  source_code_uri: https://github.com/bizowie/WWW-Bizowie-API
+  bug_tracker_uri: https://github.com/bizowie/WWW-Bizowie-API/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Ruby client for Bizowie's ERP API.
+test_files: []