lockally 0.3.1 → 0.3.3

data/lib/lockally/api/admin_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # Tenant-admin email+password login
-    # Exchanges an admin's email + password for a session token. The web console at `app.lockally.com` posts this on form submission and stores the returned token in an httpOnly cookie.  **No enumeration leak.** Wrong-email and wrong-password both return the same 401 with title \"Invalid credentials\". The argon2id verify runs even on lookup miss (well, structurally — the lookup fails fast but the response shape is constant) so timing leaks are bounded.  Tokens are prefixed `adm_sess_` and valid for 7 days. Use as the `Authorization: Bearer` value on all subsequent calls. 
+    # Exchanges an admin's email + password for a session token. The web console at `app.lockally.com` posts this on form submission and stores the returned token in an httpOnly cookie.  **No enumeration leak.** Wrong-email and wrong-password both return the same 401 with title \"Invalid credentials\". The argon2id verify runs even on lookup miss (well, structurally, the lookup fails fast but the response shape is constant) so timing leaks are bounded.  Tokens are prefixed `adm_sess_` and valid for 7 days. Use as the `Authorization: Bearer` value on all subsequent calls. 
     # @param admin_login_request [AdminLoginRequest] 
     # @param [Hash] opts the optional parameters
     # @return [AdminLogin200Response]
@@ -30,7 +30,7 @@ module Lockally
     end
 
     # Tenant-admin email+password login
-    # Exchanges an admin's email + password for a session token. The web console at `app.lockally.com` posts this on form submission and stores the returned token in an httpOnly cookie.  **No enumeration leak.** Wrong-email and wrong-password both return the same 401 with title \"Invalid credentials\". The argon2id verify runs even on lookup miss (well, structurally — the lookup fails fast but the response shape is constant) so timing leaks are bounded.  Tokens are prefixed `adm_sess_` and valid for 7 days. Use as the `Authorization: Bearer` value on all subsequent calls. 
+    # Exchanges an admin's email + password for a session token. The web console at `app.lockally.com` posts this on form submission and stores the returned token in an httpOnly cookie.  **No enumeration leak.** Wrong-email and wrong-password both return the same 401 with title \"Invalid credentials\". The argon2id verify runs even on lookup miss (well, structurally, the lookup fails fast but the response shape is constant) so timing leaks are bounded.  Tokens are prefixed `adm_sess_` and valid for 7 days. Use as the `Authorization: Bearer` value on all subsequent calls. 
     # @param admin_login_request [AdminLoginRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(AdminLogin200Response, Integer, Hash)>] AdminLogin200Response data, response status code and response headers
@@ -88,7 +88,7 @@ module Lockally
     end
 
     # Invalidate the current admin session
-    # Deletes the session row from the database. Idempotent — calling logout on an already-invalid token returns 204 anyway. 
+    # Deletes the session row from the database. Idempotent, calling logout on an already-invalid token returns 204 anyway. 
     # @param [Hash] opts the optional parameters
     # @return [nil]
     def admin_logout(opts = {})
@@ -97,7 +97,7 @@ module Lockally
     end
 
     # Invalidate the current admin session
-    # Deletes the session row from the database. Idempotent — calling logout on an already-invalid token returns 204 anyway. 
+    # Deletes the session row from the database. Idempotent, calling logout on an already-invalid token returns 204 anyway. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
     def admin_logout_with_http_info(opts = {})
@@ -145,7 +145,7 @@ module Lockally
     end
 
     # Get the current admin + tenant
-    # Returns the admin profile + tenant for the session token presented in `Authorization: Bearer`. Used by the web console's layout load function to populate the sidebar.  Returns 403 if called with an API key (lk_live_*) bearer — admin context only exists for session tokens. 
+    # Returns the admin profile + tenant for the session token presented in `Authorization: Bearer`. Used by the web console's layout load function to populate the sidebar.  Returns 403 if called with an API key (lk_live_*) bearer, admin context only exists for session tokens. 
     # @param [Hash] opts the optional parameters
     # @return [GetCurrentAdmin200Response]
     def get_current_admin(opts = {})
@@ -154,7 +154,7 @@ module Lockally
     end
 
     # Get the current admin + tenant
-    # Returns the admin profile + tenant for the session token presented in &#x60;Authorization: Bearer&#x60;. Used by the web console&#39;s layout load function to populate the sidebar.  Returns 403 if called with an API key (lk_live_*) bearer — admin context only exists for session tokens. 
+    # Returns the admin profile + tenant for the session token presented in &#x60;Authorization: Bearer&#x60;. Used by the web console&#39;s layout load function to populate the sidebar.  Returns 403 if called with an API key (lk_live_*) bearer, admin context only exists for session tokens. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(GetCurrentAdmin200Response, Integer, Hash)>] GetCurrentAdmin200Response data, response status code and response headers
     def get_current_admin_with_http_info(opts = {})

data/lib/lockally/api/admins_api.rb

@@ -206,7 +206,7 @@ module Lockally
     end
 
     # Update an admin
-    # Supply at least one of `password`, `display_name`, `role`, `disabled`.  **Safety rails.** A session bearer (adm_sess_*) cannot disable itself — use another admin or an API key (which bypasses the self-rail). Disabling the last active admin returns 409 to prevent orphaning the tenant from its console. 
+    # Supply at least one of `password`, `display_name`, `role`, `disabled`.  **Safety rails.** A session bearer (adm_sess_*) cannot disable itself, use another admin or an API key (which bypasses the self-rail). Disabling the last active admin returns 409 to prevent orphaning the tenant from its console. 
     # @param id [String] 
     # @param update_admin_request [UpdateAdminRequest] 
     # @param [Hash] opts the optional parameters
@@ -217,7 +217,7 @@ module Lockally
     end
 
     # Update an admin
-    # Supply at least one of `password`, `display_name`, `role`, `disabled`.  **Safety rails.** A session bearer (adm_sess_*) cannot disable itself — use another admin or an API key (which bypasses the self-rail). Disabling the last active admin returns 409 to prevent orphaning the tenant from its console. 
+    # Supply at least one of `password`, `display_name`, `role`, `disabled`.  **Safety rails.** A session bearer (adm_sess_*) cannot disable itself, use another admin or an API key (which bypasses the self-rail). Disabling the last active admin returns 409 to prevent orphaning the tenant from its console. 
     # @param id [String] 
     # @param update_admin_request [UpdateAdminRequest] 
     # @param [Hash] opts the optional parameters

data/lib/lockally/api/agents_api.rb

@@ -227,7 +227,7 @@ module Lockally
     end
 
     # Grant a mailbox to a key
-    # Body: {\"mailbox\": \"email or id\"}. Refused (422) for mailboxes with agent access disabled or an active E2E encryption key — the server cannot read E2E mailboxes.
+    # Body: {\"mailbox\": \"email or id\"}. Refused (422) for mailboxes with agent access disabled or an active E2E encryption key, the server cannot read E2E mailboxes.
     # @param key_id [String] 
     # @param [Hash] opts the optional parameters
     # @return [MailboxGrant]
@@ -237,7 +237,7 @@ module Lockally
     end
 
     # Grant a mailbox to a key
-    # Body: {\"mailbox\": \"email or id\"}. Refused (422) for mailboxes with agent access disabled or an active E2E encryption key — the server cannot read E2E mailboxes.
+    # Body: {\"mailbox\": \"email or id\"}. Refused (422) for mailboxes with agent access disabled or an active E2E encryption key, the server cannot read E2E mailboxes.
     # @param key_id [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(MailboxGrant, Integer, Hash)>] MailboxGrant data, response status code and response headers
@@ -617,7 +617,7 @@ module Lockally
     end
 
     # Reply in-thread (agent stream)
-    # The server builds In-Reply-To/References and defaults recipients + subject from the conversation — a minimal call is {\"text\": \"...\"}. Guarded by the reply-loop detector (≥5 outbound/10min → 429 + agent.loop_detected). Idempotency-Key required.
+    # The server builds In-Reply-To/References and defaults recipients + subject from the conversation, a minimal call is {\"text\": \"...\"}. Guarded by the reply-loop detector (≥5 outbound/10min → 429 + agent.loop_detected). Idempotency-Key required.
     # @param thread_id [String] 
     # @param idempotency_key [String] 
     # @param [Hash] opts the optional parameters
@@ -628,7 +628,7 @@ module Lockally
     end
 
     # Reply in-thread (agent stream)
-    # The server builds In-Reply-To/References and defaults recipients + subject from the conversation — a minimal call is {\&quot;text\&quot;: \&quot;...\&quot;}. Guarded by the reply-loop detector (≥5 outbound/10min → 429 + agent.loop_detected). Idempotency-Key required.
+    # The server builds In-Reply-To/References and defaults recipients + subject from the conversation, a minimal call is {\&quot;text\&quot;: \&quot;...\&quot;}. Guarded by the reply-loop detector (≥5 outbound/10min → 429 + agent.loop_detected). Idempotency-Key required.
     # @param thread_id [String] 
     # @param idempotency_key [String] 
     # @param [Hash] opts the optional parameters

data/lib/lockally/api/ai_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # LLM-classify a thread
-    # Returns {intent, urgency, summary, suggested_action} via the tenant's AI tier (BYOK or prepaid units — see /v1/ai-config). Cached per thread state: unchanged threads return the cache free; ?refresh=true forces a re-run. A failed model call charges nothing. 402 when the AI tier is off.
+    # Returns {intent, urgency, summary, suggested_action} via the tenant's AI tier (BYOK or prepaid units, see /v1/ai-config). Cached per thread state: unchanged threads return the cache free; ?refresh=true forces a re-run. A failed model call charges nothing. 402 when the AI tier is off.
     # @param thread_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [Boolean] :refresh 
@@ -31,7 +31,7 @@ module Lockally
     end
 
     # LLM-classify a thread
-    # Returns {intent, urgency, summary, suggested_action} via the tenant's AI tier (BYOK or prepaid units — see /v1/ai-config). Cached per thread state: unchanged threads return the cache free; ?refresh=true forces a re-run. A failed model call charges nothing. 402 when the AI tier is off.
+    # Returns {intent, urgency, summary, suggested_action} via the tenant's AI tier (BYOK or prepaid units, see /v1/ai-config). Cached per thread state: unchanged threads return the cache free; ?refresh=true forces a re-run. A failed model call charges nothing. 402 when the AI tier is off.
     # @param thread_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [Boolean] :refresh 

data/lib/lockally/api/aliases_api.rb

@@ -88,7 +88,7 @@ module Lockally
     end
 
     # Delete an alias
-    # Hard-delete (no soft-delete window — aliases are cheap to recreate).
+    # Hard-delete (no soft-delete window, aliases are cheap to recreate).
     # @param address [String] 
     # @param [Hash] opts the optional parameters
     # @return [nil]
@@ -98,7 +98,7 @@ module Lockally
     end
 
     # Delete an alias
-    # Hard-delete (no soft-delete window — aliases are cheap to recreate).
+    # Hard-delete (no soft-delete window, aliases are cheap to recreate).
     # @param address [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers

data/lib/lockally/api/api_keys_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # Create an API key
-    # Provisions a fresh API key for the calling tenant.  **The full `secret` is included in this response ONLY** — store it immediately. The cleartext secret is not recoverable from the argon2id hash kept server-side; rotate by creating a new key and revoking the old one. 
+    # Provisions a fresh API key for the calling tenant.  **The full `secret` is included in this response ONLY**, store it immediately. The cleartext secret is not recoverable from the argon2id hash kept server-side; rotate by creating a new key and revoking the old one. 
     # @param create_api_key_request [CreateApiKeyRequest] 
     # @param [Hash] opts the optional parameters
     # @return [CreateApiKey201Response]
@@ -30,7 +30,7 @@ module Lockally
     end
 
     # Create an API key
-    # Provisions a fresh API key for the calling tenant.  **The full `secret` is included in this response ONLY** — store it immediately. The cleartext secret is not recoverable from the argon2id hash kept server-side; rotate by creating a new key and revoking the old one. 
+    # Provisions a fresh API key for the calling tenant.  **The full `secret` is included in this response ONLY**, store it immediately. The cleartext secret is not recoverable from the argon2id hash kept server-side; rotate by creating a new key and revoking the old one. 
     # @param create_api_key_request [CreateApiKeyRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(CreateApiKey201Response, Integer, Hash)>] CreateApiKey201Response data, response status code and response headers
@@ -88,7 +88,7 @@ module Lockally
     end
 
     # List API keys
-    # Returns all API keys (active and revoked) belonging to the calling tenant. The `secret` is **never** returned — only prefix + metadata. 
+    # Returns all API keys (active and revoked) belonging to the calling tenant. The `secret` is **never** returned, only prefix + metadata. 
     # @param [Hash] opts the optional parameters
     # @return [ListApiKeys200Response]
     def list_api_keys(opts = {})
@@ -97,7 +97,7 @@ module Lockally
     end
 
     # List API keys
-    # Returns all API keys (active and revoked) belonging to the calling tenant. The &#x60;secret&#x60; is **never** returned — only prefix + metadata. 
+    # Returns all API keys (active and revoked) belonging to the calling tenant. The &#x60;secret&#x60; is **never** returned, only prefix + metadata. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(ListApiKeys200Response, Integer, Hash)>] ListApiKeys200Response data, response status code and response headers
     def list_api_keys_with_http_info(opts = {})
@@ -145,7 +145,7 @@ module Lockally
     end
 
     # Revoke an API key
-    # Soft-deletes (sets `revoked_at`) on the named key. The row stays for audit purposes; the key no longer authenticates.  You **cannot revoke the key currently being used** to make this call — that would lock you out. Use a different `tenant:admin` key. 
+    # Soft-deletes (sets `revoked_at`) on the named key. The row stays for audit purposes; the key no longer authenticates.  You **cannot revoke the key currently being used** to make this call, that would lock you out. Use a different `tenant:admin` key. 
     # @param id [String] 
     # @param [Hash] opts the optional parameters
     # @return [nil]
@@ -155,7 +155,7 @@ module Lockally
     end
 
     # Revoke an API key
-    # Soft-deletes (sets &#x60;revoked_at&#x60;) on the named key. The row stays for audit purposes; the key no longer authenticates.  You **cannot revoke the key currently being used** to make this call — that would lock you out. Use a different &#x60;tenant:admin&#x60; key. 
+    # Soft-deletes (sets &#x60;revoked_at&#x60;) on the named key. The row stays for audit purposes; the key no longer authenticates.  You **cannot revoke the key currently being used** to make this call, that would lock you out. Use a different &#x60;tenant:admin&#x60; key. 
     # @param id [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers

data/lib/lockally/api/domains_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # Register a domain
-    # Registers a new domain for the calling tenant. Generates a DKIM keypair and verification token. Returns DNS instructions the tenant must publish under their own DNS (verification TXT, SPF include, DKIM TXT, MX records to `mx1`/`mx2.lockally.com`, DMARC seed).  **Idempotent** — re-posting the same domain returns the existing record with the same DKIM keys and token (regenerating would break the tenant's published DNS). Returns 200 on idempotent hit, 201 on first create.  Returns 409 if the domain is already claimed by a different tenant. 
+    # Registers a new domain for the calling tenant. Generates a DKIM keypair and verification token. Returns DNS instructions the tenant must publish under their own DNS (verification TXT, SPF include, DKIM TXT, MX records to `mx1`/`mx2.lockally.com`, DMARC seed).  **Idempotent**, re-posting the same domain returns the existing record with the same DKIM keys and token (regenerating would break the tenant's published DNS). Returns 200 on idempotent hit, 201 on first create.  Returns 409 if the domain is already claimed by a different tenant. 
     # @param create_domain_request [CreateDomainRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Domain]
@@ -30,7 +30,7 @@ module Lockally
     end
 
     # Register a domain
-    # Registers a new domain for the calling tenant. Generates a DKIM keypair and verification token. Returns DNS instructions the tenant must publish under their own DNS (verification TXT, SPF include, DKIM TXT, MX records to `mx1`/`mx2.lockally.com`, DMARC seed).  **Idempotent** — re-posting the same domain returns the existing record with the same DKIM keys and token (regenerating would break the tenant's published DNS). Returns 200 on idempotent hit, 201 on first create.  Returns 409 if the domain is already claimed by a different tenant. 
+    # Registers a new domain for the calling tenant. Generates a DKIM keypair and verification token. Returns DNS instructions the tenant must publish under their own DNS (verification TXT, SPF include, DKIM TXT, MX records to `mx1`/`mx2.lockally.com`, DMARC seed).  **Idempotent**, re-posting the same domain returns the existing record with the same DKIM keys and token (regenerating would break the tenant's published DNS). Returns 200 on idempotent hit, 201 on first create.  Returns 409 if the domain is already claimed by a different tenant. 
     # @param create_domain_request [CreateDomainRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(Domain, Integer, Hash)>] Domain data, response status code and response headers
@@ -88,7 +88,7 @@ module Lockally
     end
 
     # Delete a domain
-    # Removes the domain registration. Refuses with 409 if any mailbox is still attached — delete the mailboxes first. 
+    # Removes the domain registration. Refuses with 409 if any mailbox is still attached, delete the mailboxes first. 
     # @param domain [String] 
     # @param [Hash] opts the optional parameters
     # @return [nil]
@@ -98,7 +98,7 @@ module Lockally
     end
 
     # Delete a domain
-    # Removes the domain registration. Refuses with 409 if any mailbox is still attached — delete the mailboxes first. 
+    # Removes the domain registration. Refuses with 409 if any mailbox is still attached, delete the mailboxes first. 
     # @param domain [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
@@ -458,7 +458,7 @@ module Lockally
     end
 
     # Force-poll DNS verification
-    # Synchronously checks the `_lockally-verify.<domain>` TXT record against the stored verification token. Returns 200 either way: the returned `verified` boolean tells you whether DNS now confirms. Caller polls until `verified: true`. In v2 a background worker auto-polls and fires a `domain.verified` webhook. 
+    # Synchronously checks the `_lockally-verify.<domain>` TXT record against the stored verification token. Returns 200 either way: the returned `verified` boolean tells you whether DNS now confirms. Caller polls until `verified: true`. A later version may have the platform auto-polls and fires a `domain.verified` webhook. 
     # @param domain [String] 
     # @param [Hash] opts the optional parameters
     # @return [Domain]
@@ -468,7 +468,7 @@ module Lockally
     end
 
     # Force-poll DNS verification
-    # Synchronously checks the &#x60;_lockally-verify.&lt;domain&gt;&#x60; TXT record against the stored verification token. Returns 200 either way: the returned &#x60;verified&#x60; boolean tells you whether DNS now confirms. Caller polls until &#x60;verified: true&#x60;. In v2 a background worker auto-polls and fires a &#x60;domain.verified&#x60; webhook. 
+    # Synchronously checks the &#x60;_lockally-verify.&lt;domain&gt;&#x60; TXT record against the stored verification token. Returns 200 either way: the returned &#x60;verified&#x60; boolean tells you whether DNS now confirms. Caller polls until &#x60;verified: true&#x60;. A later version may have the platform auto-polls and fires a &#x60;domain.verified&#x60; webhook. 
     # @param domain [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(Domain, Integer, Hash)>] Domain data, response status code and response headers

data/lib/lockally/api/mailboxes_api.rb

@@ -92,7 +92,7 @@ module Lockally
     end
 
     # Create a mailbox
-    # Creates a mailbox on a tenant-verified domain. If `password` is omitted, lockally generates a 16-char password and returns it in the response — shown once.  **Gate.** The mailbox's domain must already be registered AND verified for this tenant (via `/v1/domains` + `/v1/domains/{domain}/verify`).  **Idempotent.** Re-posting the same email returns the existing mailbox UNTOUCHED — password is NOT regenerated. To change a password, use PATCH instead. 
+    # Creates a mailbox on a tenant-verified domain. If `password` is omitted, lockally generates a 16-char password and returns it in the response, shown once.  **Gate.** The mailbox's domain must already be registered AND verified for this tenant (via `/v1/domains` + `/v1/domains/{domain}/verify`).  **Idempotent.** Re-posting the same email returns the existing mailbox UNTOUCHED, password is NOT regenerated. To change a password, use PATCH instead. 
     # @param create_mailbox_request [CreateMailboxRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Mailbox]
@@ -102,7 +102,7 @@ module Lockally
     end
 
     # Create a mailbox
-    # Creates a mailbox on a tenant-verified domain. If `password` is omitted, lockally generates a 16-char password and returns it in the response — shown once.  **Gate.** The mailbox's domain must already be registered AND verified for this tenant (via `/v1/domains` + `/v1/domains/{domain}/verify`).  **Idempotent.** Re-posting the same email returns the existing mailbox UNTOUCHED — password is NOT regenerated. To change a password, use PATCH instead. 
+    # Creates a mailbox on a tenant-verified domain. If `password` is omitted, lockally generates a 16-char password and returns it in the response, shown once.  **Gate.** The mailbox's domain must already be registered AND verified for this tenant (via `/v1/domains` + `/v1/domains/{domain}/verify`).  **Idempotent.** Re-posting the same email returns the existing mailbox UNTOUCHED, password is NOT regenerated. To change a password, use PATCH instead. 
     # @param create_mailbox_request [CreateMailboxRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(Mailbox, Integer, Hash)>] Mailbox data, response status code and response headers
@@ -223,7 +223,7 @@ module Lockally
     end
 
     # Remove the vacation responder
-    # Idempotent — 204 whether or not a row existed.
+    # Idempotent, 204 whether or not a row existed.
     # @param email [String] 
     # @param [Hash] opts the optional parameters
     # @return [nil]
@@ -233,7 +233,7 @@ module Lockally
     end
 
     # Remove the vacation responder
-    # Idempotent — 204 whether or not a row existed.
+    # Idempotent, 204 whether or not a row existed.
     # @param email [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
@@ -286,7 +286,7 @@ module Lockally
     end
 
     # Download a previously-issued mailbox export
-    # Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404 — tokens are single-use. 
+    # Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404, tokens are single-use. 
     # @param email [String] 
     # @param token [String] 
     # @param [Hash] opts the optional parameters
@@ -297,7 +297,7 @@ module Lockally
     end
 
     # Download a previously-issued mailbox export
-    # Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404 — tokens are single-use. 
+    # Public endpoint (no Authorization header). Validates the one-shot token from the URL, marks it used, and streams an mbox file. Second GET with the same token returns 404, tokens are single-use. 
     # @param email [String] 
     # @param token [String] 
     # @param [Hash] opts the optional parameters
@@ -356,7 +356,7 @@ module Lockally
     end
 
     # Request a mailbox export
-    # Issues a one-shot \"presigned\" download URL for the mailbox's content in mbox format. The URL works without an Authorization header — the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.  **v1 caveat:** the synthesized mbox only contains outbound mail (from `lockally.messages`). v2 swaps in Stalwart's export primitive for full inbox + folder structure + flags. The endpoint contract stays unchanged.  **Scope changed:** this used to accept `mailboxes:read`. It takes any mailbox in the tenant and returns that mailbox's mail, so it now requires `tenant:admin`, matching `POST /v1/ediscovery/export`. A key scoped `mailboxes:read` gets 403 and has to be reissued; admin console sessions are unaffected. 
+    # Issues a one-shot \"presigned\" download URL for the mailbox's content in mbox format. The URL works without an Authorization header, the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.  **v1 caveat:** the synthesized mbox only contains outbound mail (sent mail only). A later version will cover received mail for full inbox + folder structure + flags. The endpoint contract stays unchanged.  **Scope changed:** this used to accept `mailboxes:read`. It takes any mailbox in the tenant and returns that mailbox's mail, so it now requires `tenant:admin`, matching `POST /v1/ediscovery/export`. A key scoped `mailboxes:read` gets 403 and has to be reissued; admin console sessions are unaffected. 
     # @param email [String] 
     # @param [Hash] opts the optional parameters
     # @return [ExportMailbox201Response]
@@ -366,7 +366,7 @@ module Lockally
     end
 
     # Request a mailbox export
-    # Issues a one-shot \&quot;presigned\&quot; download URL for the mailbox&#39;s content in mbox format. The URL works without an Authorization header — the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.  **v1 caveat:** the synthesized mbox only contains outbound mail (from &#x60;lockally.messages&#x60;). v2 swaps in Stalwart&#39;s export primitive for full inbox + folder structure + flags. The endpoint contract stays unchanged.  **Scope changed:** this used to accept &#x60;mailboxes:read&#x60;. It takes any mailbox in the tenant and returns that mailbox&#39;s mail, so it now requires &#x60;tenant:admin&#x60;, matching &#x60;POST /v1/ediscovery/export&#x60;. A key scoped &#x60;mailboxes:read&#x60; gets 403 and has to be reissued; admin console sessions are unaffected. 
+    # Issues a one-shot \&quot;presigned\&quot; download URL for the mailbox&#39;s content in mbox format. The URL works without an Authorization header, the token in the query string is the authz. TTL is 5 minutes; the token is consumed on first GET.  **v1 caveat:** the synthesized mbox only contains outbound mail (sent mail only). A later version will cover received mail for full inbox + folder structure + flags. The endpoint contract stays unchanged.  **Scope changed:** this used to accept &#x60;mailboxes:read&#x60;. It takes any mailbox in the tenant and returns that mailbox&#39;s mail, so it now requires &#x60;tenant:admin&#x60;, matching &#x60;POST /v1/ediscovery/export&#x60;. A key scoped &#x60;mailboxes:read&#x60; gets 403 and has to be reissued; admin console sessions are unaffected. 
     # @param email [String] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(ExportMailbox201Response, Integer, Hash)>] ExportMailbox201Response data, response status code and response headers
@@ -543,7 +543,7 @@ module Lockally
     end
 
     # List mailboxes
-    # Returns mailboxes under the calling tenant — active and soft-deleted. `?limit=N` between 1 and 200 (default 50). 
+    # Returns mailboxes under the calling tenant, active and soft-deleted. `?limit=N` between 1 and 200 (default 50). 
     # @param [Hash] opts the optional parameters
     # @option opts [Integer] :limit  (default to 50)
     # @return [ListMailboxes200Response]
@@ -553,7 +553,7 @@ module Lockally
     end
 
     # List mailboxes
-    # Returns mailboxes under the calling tenant — active and soft-deleted. &#x60;?limit&#x3D;N&#x60; between 1 and 200 (default 50). 
+    # Returns mailboxes under the calling tenant, active and soft-deleted. &#x60;?limit&#x3D;N&#x60; between 1 and 200 (default 50). 
     # @param [Hash] opts the optional parameters
     # @option opts [Integer] :limit  (default to 50)
     # @return [Array<(ListMailboxes200Response, Integer, Hash)>] ListMailboxes200Response data, response status code and response headers
@@ -796,7 +796,7 @@ module Lockally
     end
 
     # Set the vacation responder
-    # Upsert — same endpoint creates or replaces the rule. Clears `synced_at`; the rule is staged on lockally until a sync worker pushes it to the mail server. 
+    # Upsert, same endpoint creates or replaces the rule. Clears `synced_at`; the rule is staged until a later sync pushes it to the mail server. 
     # @param email [String] 
     # @param set_vacation_responder_request [SetVacationResponderRequest] 
     # @param [Hash] opts the optional parameters
@@ -807,7 +807,7 @@ module Lockally
     end
 
     # Set the vacation responder
-    # Upsert — same endpoint creates or replaces the rule. Clears &#x60;synced_at&#x60;; the rule is staged on lockally until a sync worker pushes it to the mail server. 
+    # Upsert, same endpoint creates or replaces the rule. Clears &#x60;synced_at&#x60;; the rule is staged until a later sync pushes it to the mail server. 
     # @param email [String] 
     # @param set_vacation_responder_request [SetVacationResponderRequest] 
     # @param [Hash] opts the optional parameters

data/lib/lockally/api/send_api.rb

@@ -144,7 +144,7 @@ module Lockally
     end
 
     # Aggregate delivery stats
-    # Counts by delivery outcome (delivered/bounced/deferred/complaint) plus rates over a window, from the delivery-event store. Privacy-first: this reflects what receiving servers reported, NOT whether a human opened the mail — Lockally does no open/click tracking. 
+    # Counts by delivery outcome (delivered/bounced/deferred/complaint) plus rates over a window, from the delivery-event store. Privacy-first: this reflects what receiving servers reported, NOT whether a human opened the mail, Lockally does no open/click tracking. 
     # @param [Hash] opts the optional parameters
     # @option opts [Time] :from Window start (default 7 days ago).
     # @option opts [Time] :to Window end (default now).
@@ -156,7 +156,7 @@ module Lockally
     end
 
     # Aggregate delivery stats
-    # Counts by delivery outcome (delivered/bounced/deferred/complaint) plus rates over a window, from the delivery-event store. Privacy-first: this reflects what receiving servers reported, NOT whether a human opened the mail — Lockally does no open/click tracking. 
+    # Counts by delivery outcome (delivered/bounced/deferred/complaint) plus rates over a window, from the delivery-event store. Privacy-first: this reflects what receiving servers reported, NOT whether a human opened the mail, Lockally does no open/click tracking. 
     # @param [Hash] opts the optional parameters
     # @option opts [Time] :from Window start (default 7 days ago).
     # @option opts [Time] :to Window end (default now).
@@ -210,7 +210,7 @@ module Lockally
     end
 
     # List outbound messages
-    # Returns recent outbound messages for the calling tenant, sorted newest first. Backs the send-status pill in the SvelteKit /sends view and the outbound search box. 
+    # Returns recent outbound messages for the calling tenant, sorted newest first. 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :status 
     # @option opts [String] :sender Exact match against the `from` mailbox.
@@ -225,7 +225,7 @@ module Lockally
     end
 
     # List outbound messages
-    # Returns recent outbound messages for the calling tenant, sorted newest first. Backs the send-status pill in the SvelteKit /sends view and the outbound search box. 
+    # Returns recent outbound messages for the calling tenant, sorted newest first. 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :status 
     # @option opts [String] :sender Exact match against the `from` mailbox.
@@ -293,7 +293,7 @@ module Lockally
     end
 
     # Send an email
-    # Submits an email for delivery via lockally. Returns 202 immediately once the message is accepted into lockally's queue; the actual SMTP submission to the recipient is async. Track delivery via `GET /v1/messages/{id}` or webhook subscriptions for `delivery.delivered` / `delivery.bounced` / `delivery.complaint`.  **Idempotency-Key required.** Per design L7 — any unique string per send, 24-hour dedupe window. Repeated calls with the same key return byte-exact the original response and do NOT create a duplicate message.  **Sender authorisation.** `from` must be an address the calling tenant owns on a verified domain. A mailbox always qualifies. On business and combined accounts an **alias** qualifies too, so a send-only address such as `no-reply@` need not be a billed seat. An alias on an unverified domain, or one belonging to another account, is refused with `403`. A catch-all creates no aliases and so grants no sending rights.  **Rate cap.** Per-tenant `rate_cap_per_min` (returned on `/v1/tenant`) is enforced — 429 with `Retry-After: 60` once tripped.  **Recipient warning.** Over 25 total recipients (To+Cc+Bcc) sets a `warning` field in the response — large fan-outs queue noticeably at scale. Hard cap is 100/send.  **Not every success is a 202.** Check the status code, not just the body. A `200` means nothing was queued: either every recipient was already suppressed, or the call used a test key and the send was simulated. Both are successes, and neither produces a real delivery. See the `200` response below.  **Warm-up headers.** While the platform is in its outbound warm-up ramp, accepted sends carry `X-Warmup-Day`, `X-Warmup-Daily-Cap` and `X-Warmup-Used-Today`. They describe a platform-wide cap shared by every tenant, not your own allowance, and they disappear once the ramp finishes. Hitting the cap returns 429. 
+    # Submits an email for delivery via lockally. Returns 202 immediately once the message is accepted into lockally's queue; the actual SMTP submission to the recipient is async. Track delivery via `GET /v1/messages/{id}` or webhook subscriptions for `delivery.delivered` / `delivery.bounced` / `delivery.complaint`.  **Idempotency-Key required.** Any unique string per send, 24-hour dedupe window. Repeated calls with the same key return byte-exact the original response and do NOT create a duplicate message.  **Sender authorisation.** `from` must be an address the calling tenant owns on a verified domain. A mailbox always qualifies. On business and combined accounts an **alias** qualifies too, so a send-only address such as `no-reply@` need not be a billed seat. An alias on an unverified domain, or one belonging to another account, is refused with `403`. A catch-all creates no aliases and so grants no sending rights.  **Rate cap.** Per-tenant `rate_cap_per_min` (returned on `/v1/tenant`) is enforced, 429 with `Retry-After: 60` once tripped.  **Recipient warning.** Over 25 total recipients (To+Cc+Bcc) sets a `warning` field in the response, large fan-outs queue noticeably at scale. Hard cap is 100/send.  **Not every success is a 202.** Check the status code, not just the body. A `200` means nothing was queued: either every recipient was already suppressed, or the call used a test key and the send was simulated. Both are successes, and neither produces a real delivery. See the `200` response below.  **Warm-up headers.** While the platform is in its outbound warm-up ramp, accepted sends carry `X-Warmup-Day`, `X-Warmup-Daily-Cap` and `X-Warmup-Used-Today`. They describe a platform-wide cap shared by every tenant, not your own allowance, and they disappear once the ramp finishes. Hitting the cap returns 429. 
     # @param idempotency_key [String] 
     # @param send_email_request [SendEmailRequest] 
     # @param [Hash] opts the optional parameters
@@ -304,7 +304,7 @@ module Lockally
     end
 
     # Send an email
-    # Submits an email for delivery via lockally. Returns 202 immediately once the message is accepted into lockally's queue; the actual SMTP submission to the recipient is async. Track delivery via `GET /v1/messages/{id}` or webhook subscriptions for `delivery.delivered` / `delivery.bounced` / `delivery.complaint`.  **Idempotency-Key required.** Per design L7 — any unique string per send, 24-hour dedupe window. Repeated calls with the same key return byte-exact the original response and do NOT create a duplicate message.  **Sender authorisation.** `from` must be an address the calling tenant owns on a verified domain. A mailbox always qualifies. On business and combined accounts an **alias** qualifies too, so a send-only address such as `no-reply@` need not be a billed seat. An alias on an unverified domain, or one belonging to another account, is refused with `403`. A catch-all creates no aliases and so grants no sending rights.  **Rate cap.** Per-tenant `rate_cap_per_min` (returned on `/v1/tenant`) is enforced — 429 with `Retry-After: 60` once tripped.  **Recipient warning.** Over 25 total recipients (To+Cc+Bcc) sets a `warning` field in the response — large fan-outs queue noticeably at scale. Hard cap is 100/send.  **Not every success is a 202.** Check the status code, not just the body. A `200` means nothing was queued: either every recipient was already suppressed, or the call used a test key and the send was simulated. Both are successes, and neither produces a real delivery. See the `200` response below.  **Warm-up headers.** While the platform is in its outbound warm-up ramp, accepted sends carry `X-Warmup-Day`, `X-Warmup-Daily-Cap` and `X-Warmup-Used-Today`. They describe a platform-wide cap shared by every tenant, not your own allowance, and they disappear once the ramp finishes. Hitting the cap returns 429. 
+    # Submits an email for delivery via lockally. Returns 202 immediately once the message is accepted into lockally's queue; the actual SMTP submission to the recipient is async. Track delivery via `GET /v1/messages/{id}` or webhook subscriptions for `delivery.delivered` / `delivery.bounced` / `delivery.complaint`.  **Idempotency-Key required.** Any unique string per send, 24-hour dedupe window. Repeated calls with the same key return byte-exact the original response and do NOT create a duplicate message.  **Sender authorisation.** `from` must be an address the calling tenant owns on a verified domain. A mailbox always qualifies. On business and combined accounts an **alias** qualifies too, so a send-only address such as `no-reply@` need not be a billed seat. An alias on an unverified domain, or one belonging to another account, is refused with `403`. A catch-all creates no aliases and so grants no sending rights.  **Rate cap.** Per-tenant `rate_cap_per_min` (returned on `/v1/tenant`) is enforced, 429 with `Retry-After: 60` once tripped.  **Recipient warning.** Over 25 total recipients (To+Cc+Bcc) sets a `warning` field in the response, large fan-outs queue noticeably at scale. Hard cap is 100/send.  **Not every success is a 202.** Check the status code, not just the body. A `200` means nothing was queued: either every recipient was already suppressed, or the call used a test key and the send was simulated. Both are successes, and neither produces a real delivery. See the `200` response below.  **Warm-up headers.** While the platform is in its outbound warm-up ramp, accepted sends carry `X-Warmup-Day`, `X-Warmup-Daily-Cap` and `X-Warmup-Used-Today`. They describe a platform-wide cap shared by every tenant, not your own allowance, and they disappear once the ramp finishes. Hitting the cap returns 429. 
     # @param idempotency_key [String] 
     # @param send_email_request [SendEmailRequest] 
     # @param [Hash] opts the optional parameters
@@ -372,7 +372,7 @@ module Lockally
     end
 
     # Send a batch of emails
-    # Sends up to 500 messages in one call. Each is validated and enqueued independently — a bad message fails only its own slot (partial success, HTTP 200). One `Idempotency-Key` header covers the batch; per-message keys are derived as `<key>:<index>`. 
+    # Sends up to 500 messages in one call. Each is validated and enqueued independently, a bad message fails only its own slot (partial success, HTTP 200). One `Idempotency-Key` header covers the batch; per-message keys are derived as `<key>:<index>`. 
     # @param idempotency_key [String] 
     # @param send_email_batch_request [SendEmailBatchRequest] 
     # @param [Hash] opts the optional parameters
@@ -383,7 +383,7 @@ module Lockally
     end
 
     # Send a batch of emails
-    # Sends up to 500 messages in one call. Each is validated and enqueued independently — a bad message fails only its own slot (partial success, HTTP 200). One &#x60;Idempotency-Key&#x60; header covers the batch; per-message keys are derived as &#x60;&lt;key&gt;:&lt;index&gt;&#x60;. 
+    # Sends up to 500 messages in one call. Each is validated and enqueued independently, a bad message fails only its own slot (partial success, HTTP 200). One &#x60;Idempotency-Key&#x60; header covers the batch; per-message keys are derived as &#x60;&lt;key&gt;:&lt;index&gt;&#x60;. 
     # @param idempotency_key [String] 
     # @param send_email_batch_request [SendEmailBatchRequest] 
     # @param [Hash] opts the optional parameters

data/lib/lockally/api/tenant_api.rb

@@ -77,7 +77,7 @@ module Lockally
     end
 
     # Usage snapshot
-    # Returns the tenant's current usage + cap consumption. Designed for poll-based alerting on the integrator side (e.g. \"warn when daily quota is 80% used\"). Refreshed live from Postgres — there is no cache, so callers should poll at most once per minute. 
+    # Returns the tenant's current usage + cap consumption. Designed for poll-based alerting on the integrator side (e.g. \"warn when daily quota is 80% used\"). Computed live on request, so there is no cache, so callers should poll at most once per minute. 
     # @param [Hash] opts the optional parameters
     # @return [GetUsage200Response]
     def get_usage(opts = {})
@@ -86,7 +86,7 @@ module Lockally
     end
 
     # Usage snapshot
-    # Returns the tenant's current usage + cap consumption. Designed for poll-based alerting on the integrator side (e.g. \"warn when daily quota is 80% used\"). Refreshed live from Postgres — there is no cache, so callers should poll at most once per minute. 
+    # Returns the tenant's current usage + cap consumption. Designed for poll-based alerting on the integrator side (e.g. \"warn when daily quota is 80% used\"). Computed live on request, so there is no cache, so callers should poll at most once per minute. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(GetUsage200Response, Integer, Hash)>] GetUsage200Response data, response status code and response headers
     def get_usage_with_http_info(opts = {})

data/lib/lockally/api/test_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # Simulate an inbound email (test keys only)
-    # Runs a synthetic message through the REAL indexing pipeline — thread adoption, deterministic extraction (incl. injection_risk), and the message.received webhook — so the whole agent loop is testable without a real domain or MTA. Requires an lk_test_* key (create with {\"test\": true} on POST /v1/api-keys). Body: {mailbox, from, subject, text, in_reply_to?, references?}.
+    # Runs a synthetic message through the REAL indexing pipeline, thread adoption, deterministic extraction (incl. injection_risk), and the message.received webhook, so the whole agent loop is testable without a real domain or MTA. Requires an lk_test_* key (create with {\"test\": true} on POST /v1/api-keys). Body: {mailbox, from, subject, text, in_reply_to?, references?}.
     # @param [Hash] opts the optional parameters
     # @return [SimulatedInbound]
     def simulate_inbound_email(opts = {})
@@ -29,7 +29,7 @@ module Lockally
     end
 
     # Simulate an inbound email (test keys only)
-    # Runs a synthetic message through the REAL indexing pipeline — thread adoption, deterministic extraction (incl. injection_risk), and the message.received webhook — so the whole agent loop is testable without a real domain or MTA. Requires an lk_test_* key (create with {\"test\": true} on POST /v1/api-keys). Body: {mailbox, from, subject, text, in_reply_to?, references?}.
+    # Runs a synthetic message through the REAL indexing pipeline, thread adoption, deterministic extraction (incl. injection_risk), and the message.received webhook, so the whole agent loop is testable without a real domain or MTA. Requires an lk_test_* key (create with {\"test\": true} on POST /v1/api-keys). Body: {mailbox, from, subject, text, in_reply_to?, references?}.
     # @param [Hash] opts the optional parameters
     # @return [Array<(SimulatedInbound, Integer, Hash)>] SimulatedInbound data, response status code and response headers
     def simulate_inbound_email_with_http_info(opts = {})

data/lib/lockally/api/webhooks_api.rb

@@ -20,7 +20,7 @@ module Lockally
       @api_client = api_client
     end
     # Create a webhook
-    # Subscribes a URL to one or more event types. Returns the `signing_secret` ONCE in the response — store it immediately. The dispatcher signs every outbound POST per design L3:      X-Lockally-Signature: t=<unix>,v1=<hex(hmac_sha256(secret, t + \".\" + body))>  Verify on your end using HMAC-SHA256 with a 5-minute timestamp window (replay protection). A reference verifier ships in [internal/webhook](https://github.com/ucheigwedinma/lockally/blob/main/internal/webhook/sign.go).  Event names: see the [event catalogue](https://github.com/ucheigwedinma/lockally/blob/main/docs/v1-design.md#64-webhook-event-catalogue-v1). 
+    # Subscribes a URL to one or more event types. Returns the `signing_secret` ONCE in the response, store it immediately. Every outbound POST is signed:      X-Lockally-Signature: t=<unix>,v1=<hex(hmac_sha256(secret, t + \".\" + body))>  Verify on your end using HMAC-SHA256 with a 5-minute timestamp window (replay protection). A reference verifier ships in [Signature verification](https://developers.lockally.com/webhooks/verification/).  Event names: see the [event catalogue](https://developers.lockally.com/webhooks/events/). 
     # @param create_webhook_request [CreateWebhookRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Webhook]
@@ -30,7 +30,7 @@ module Lockally
     end
 
     # Create a webhook
-    # Subscribes a URL to one or more event types. Returns the &#x60;signing_secret&#x60; ONCE in the response — store it immediately. The dispatcher signs every outbound POST per design L3:      X-Lockally-Signature: t&#x3D;&lt;unix&gt;,v1&#x3D;&lt;hex(hmac_sha256(secret, t + \&quot;.\&quot; + body))&gt;  Verify on your end using HMAC-SHA256 with a 5-minute timestamp window (replay protection). A reference verifier ships in [internal/webhook](https://github.com/ucheigwedinma/lockally/blob/main/internal/webhook/sign.go).  Event names: see the [event catalogue](https://github.com/ucheigwedinma/lockally/blob/main/docs/v1-design.md#64-webhook-event-catalogue-v1). 
+    # Subscribes a URL to one or more event types. Returns the &#x60;signing_secret&#x60; ONCE in the response, store it immediately. Every outbound POST is signed:      X-Lockally-Signature: t&#x3D;&lt;unix&gt;,v1&#x3D;&lt;hex(hmac_sha256(secret, t + \&quot;.\&quot; + body))&gt;  Verify on your end using HMAC-SHA256 with a 5-minute timestamp window (replay protection). A reference verifier ships in [Signature verification](https://developers.lockally.com/webhooks/verification/).  Event names: see the [event catalogue](https://developers.lockally.com/webhooks/events/). 
     # @param create_webhook_request [CreateWebhookRequest] 
     # @param [Hash] opts the optional parameters
     # @return [Array<(Webhook, Integer, Hash)>] Webhook data, response status code and response headers
@@ -151,7 +151,7 @@ module Lockally
     end
 
     # List webhooks
-    # Returns the calling tenant's webhook subscriptions. Never returns the signing secret — only metadata. 
+    # Returns the calling tenant's webhook subscriptions. Never returns the signing secret, only metadata. 
     # @param [Hash] opts the optional parameters
     # @return [ListWebhooks200Response]
     def list_webhooks(opts = {})
@@ -160,7 +160,7 @@ module Lockally
     end
 
     # List webhooks
-    # Returns the calling tenant&#39;s webhook subscriptions. Never returns the signing secret — only metadata. 
+    # Returns the calling tenant&#39;s webhook subscriptions. Never returns the signing secret, only metadata. 
     # @param [Hash] opts the optional parameters
     # @return [Array<(ListWebhooks200Response, Integer, Hash)>] ListWebhooks200Response data, response status code and response headers
     def list_webhooks_with_http_info(opts = {})
@@ -208,7 +208,7 @@ module Lockally
     end
 
     # Update a webhook
-    # Supply at least one of `url`, `events`, `paused`. Setting `paused` to `false` ALSO resets `consecutive_failures` to 0 — re-arms the 50-failure auto-pause counter. 
+    # Supply at least one of `url`, `events`, `paused`. Setting `paused` to `false` ALSO resets `consecutive_failures` to 0, re-arms the 50-failure auto-pause counter. 
     # @param id [String] 
     # @param update_webhook_request [UpdateWebhookRequest] 
     # @param [Hash] opts the optional parameters
@@ -219,7 +219,7 @@ module Lockally
     end
 
     # Update a webhook
-    # Supply at least one of &#x60;url&#x60;, &#x60;events&#x60;, &#x60;paused&#x60;. Setting &#x60;paused&#x60; to &#x60;false&#x60; ALSO resets &#x60;consecutive_failures&#x60; to 0 — re-arms the 50-failure auto-pause counter. 
+    # Supply at least one of &#x60;url&#x60;, &#x60;events&#x60;, &#x60;paused&#x60;. Setting &#x60;paused&#x60; to &#x60;false&#x60; ALSO resets &#x60;consecutive_failures&#x60; to 0, re-arms the 50-failure auto-pause counter. 
     # @param id [String] 
     # @param update_webhook_request [UpdateWebhookRequest] 
     # @param [Hash] opts the optional parameters