ngrok-api 0.9.0 → 0.16.0

data/docs/NgrokAPI/Services.html

@@ -6,7 +6,7 @@
 <title>
   Module: NgrokAPI::Services
   
-    &mdash; Documentation by YARD 0.9.26
+    &mdash; Documentation by YARD 0.9.27
   
 </title>
 
@@ -78,8 +78,8 @@
   
   <dl>
     <dt>Defined in:</dt>
-    <dd>lib/ngrokapi/services/api_keys_client.rb<span class="defines">,<br />
-  lib/ngrokapi/services/reserved_domains_client.rb,<br /> lib/ngrokapi/services/tls_certificates_client.rb,<br /> lib/ngrokapi/services/endpoint_configurations_client.rb</span>
+    <dd>lib/ngrokapi/services/tunnels_client.rb<span class="defines">,<br />
+  lib/ngrokapi/services/api_keys_client.rb,<br /> lib/ngrokapi/services/credentials_client.rb,<br /> lib/ngrokapi/services/ip_policies_client.rb,<br /> lib/ngrokapi/services/abuse_reports_client.rb,<br /> lib/ngrokapi/services/event_sources_client.rb,<br /> lib/ngrokapi/services/event_streams_client.rb,<br /> lib/ngrokapi/services/reserved_addrs_client.rb,<br /> lib/ngrokapi/services/agent_ingresses_client.rb,<br /> lib/ngrokapi/services/ip_policy_rules_client.rb,<br /> lib/ngrokapi/services/ip_restrictions_client.rb,<br /> lib/ngrokapi/services/ssh_credentials_client.rb,<br /> lib/ngrokapi/services/tunnel_sessions_client.rb,<br /> lib/ngrokapi/services/reserved_domains_client.rb,<br /> lib/ngrokapi/services/tls_certificates_client.rb,<br /> lib/ngrokapi/services/event_destinations_client.rb,<br /> lib/ngrokapi/services/event_subscriptions_client.rb,<br /> lib/ngrokapi/services/endpoint_oidc_module_client.rb,<br /> lib/ngrokapi/services/endpoint_saml_module_client.rb,<br /> lib/ngrokapi/services/ssh_host_certificates_client.rb,<br /> lib/ngrokapi/services/ssh_user_certificates_client.rb,<br /> lib/ngrokapi/services/endpoint_o_auth_module_client.rb,<br /> lib/ngrokapi/services/certificate_authorities_client.rb,<br /> lib/ngrokapi/services/endpoint_configurations_client.rb,<br /> lib/ngrokapi/services/endpoint_logging_module_client.rb,<br /> lib/ngrokapi/services/endpoint_ip_policy_module_client.rb,<br /> lib/ngrokapi/services/endpoint_mutual_tls_module_client.rb,<br /> lib/ngrokapi/services/endpoint_compression_module_client.rb,<br /> lib/ngrokapi/services/ssh_certificate_authorities_client.rb,<br /> lib/ngrokapi/services/endpoint_circuit_breaker_module_client.rb,<br /> lib/ngrokapi/services/endpoint_request_headers_module_client.rb,<br /> lib/ngrokapi/services/endpoint_tls_termination_module_client.rb,<br /> lib/ngrokapi/services/endpoint_response_headers_module_client.rb,<br /> lib/ngrokapi/services/endpoint_webhook_validation_module_client.rb</span>
 </dd>
   </dl>
   
@@ -91,7 +91,7 @@
     
   
     
-      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Services/ApiKeysClient.html" title="NgrokAPI::Services::ApiKeysClient (class)">ApiKeysClient</a></span>, <span class='object_link'><a href="Services/EndpointConfigurationsClient.html" title="NgrokAPI::Services::EndpointConfigurationsClient (class)">EndpointConfigurationsClient</a></span>, <span class='object_link'><a href="Services/ReservedDomainsClient.html" title="NgrokAPI::Services::ReservedDomainsClient (class)">ReservedDomainsClient</a></span>, <span class='object_link'><a href="Services/TlsCertificatesClient.html" title="NgrokAPI::Services::TlsCertificatesClient (class)">TlsCertificatesClient</a></span>
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Services/APIKeysClient.html" title="NgrokAPI::Services::APIKeysClient (class)">APIKeysClient</a></span>, <span class='object_link'><a href="Services/AbuseReportsClient.html" title="NgrokAPI::Services::AbuseReportsClient (class)">AbuseReportsClient</a></span>, <span class='object_link'><a href="Services/AgentIngressesClient.html" title="NgrokAPI::Services::AgentIngressesClient (class)">AgentIngressesClient</a></span>, <span class='object_link'><a href="Services/CertificateAuthoritiesClient.html" title="NgrokAPI::Services::CertificateAuthoritiesClient (class)">CertificateAuthoritiesClient</a></span>, <span class='object_link'><a href="Services/CredentialsClient.html" title="NgrokAPI::Services::CredentialsClient (class)">CredentialsClient</a></span>, <span class='object_link'><a href="Services/EndpointCircuitBreakerModuleClient.html" title="NgrokAPI::Services::EndpointCircuitBreakerModuleClient (class)">EndpointCircuitBreakerModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointCompressionModuleClient.html" title="NgrokAPI::Services::EndpointCompressionModuleClient (class)">EndpointCompressionModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointConfigurationsClient.html" title="NgrokAPI::Services::EndpointConfigurationsClient (class)">EndpointConfigurationsClient</a></span>, <span class='object_link'><a href="Services/EndpointIPPolicyModuleClient.html" title="NgrokAPI::Services::EndpointIPPolicyModuleClient (class)">EndpointIPPolicyModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointLoggingModuleClient.html" title="NgrokAPI::Services::EndpointLoggingModuleClient (class)">EndpointLoggingModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointMutualTLSModuleClient.html" title="NgrokAPI::Services::EndpointMutualTLSModuleClient (class)">EndpointMutualTLSModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointOAuthModuleClient.html" title="NgrokAPI::Services::EndpointOAuthModuleClient (class)">EndpointOAuthModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointOIDCModuleClient.html" title="NgrokAPI::Services::EndpointOIDCModuleClient (class)">EndpointOIDCModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointRequestHeadersModuleClient.html" title="NgrokAPI::Services::EndpointRequestHeadersModuleClient (class)">EndpointRequestHeadersModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointResponseHeadersModuleClient.html" title="NgrokAPI::Services::EndpointResponseHeadersModuleClient (class)">EndpointResponseHeadersModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointSAMLModuleClient.html" title="NgrokAPI::Services::EndpointSAMLModuleClient (class)">EndpointSAMLModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointTLSTerminationModuleClient.html" title="NgrokAPI::Services::EndpointTLSTerminationModuleClient (class)">EndpointTLSTerminationModuleClient</a></span>, <span class='object_link'><a href="Services/EndpointWebhookValidationModuleClient.html" title="NgrokAPI::Services::EndpointWebhookValidationModuleClient (class)">EndpointWebhookValidationModuleClient</a></span>, <span class='object_link'><a href="Services/EventDestinationsClient.html" title="NgrokAPI::Services::EventDestinationsClient (class)">EventDestinationsClient</a></span>, <span class='object_link'><a href="Services/EventSourcesClient.html" title="NgrokAPI::Services::EventSourcesClient (class)">EventSourcesClient</a></span>, <span class='object_link'><a href="Services/EventStreamsClient.html" title="NgrokAPI::Services::EventStreamsClient (class)">EventStreamsClient</a></span>, <span class='object_link'><a href="Services/EventSubscriptionsClient.html" title="NgrokAPI::Services::EventSubscriptionsClient (class)">EventSubscriptionsClient</a></span>, <span class='object_link'><a href="Services/IPPoliciesClient.html" title="NgrokAPI::Services::IPPoliciesClient (class)">IPPoliciesClient</a></span>, <span class='object_link'><a href="Services/IPPolicyRulesClient.html" title="NgrokAPI::Services::IPPolicyRulesClient (class)">IPPolicyRulesClient</a></span>, <span class='object_link'><a href="Services/IPRestrictionsClient.html" title="NgrokAPI::Services::IPRestrictionsClient (class)">IPRestrictionsClient</a></span>, <span class='object_link'><a href="Services/ReservedAddrsClient.html" title="NgrokAPI::Services::ReservedAddrsClient (class)">ReservedAddrsClient</a></span>, <span class='object_link'><a href="Services/ReservedDomainsClient.html" title="NgrokAPI::Services::ReservedDomainsClient (class)">ReservedDomainsClient</a></span>, <span class='object_link'><a href="Services/SSHCertificateAuthoritiesClient.html" title="NgrokAPI::Services::SSHCertificateAuthoritiesClient (class)">SSHCertificateAuthoritiesClient</a></span>, <span class='object_link'><a href="Services/SSHCredentialsClient.html" title="NgrokAPI::Services::SSHCredentialsClient (class)">SSHCredentialsClient</a></span>, <span class='object_link'><a href="Services/SSHHostCertificatesClient.html" title="NgrokAPI::Services::SSHHostCertificatesClient (class)">SSHHostCertificatesClient</a></span>, <span class='object_link'><a href="Services/SSHUserCertificatesClient.html" title="NgrokAPI::Services::SSHUserCertificatesClient (class)">SSHUserCertificatesClient</a></span>, <span class='object_link'><a href="Services/TLSCertificatesClient.html" title="NgrokAPI::Services::TLSCertificatesClient (class)">TLSCertificatesClient</a></span>, <span class='object_link'><a href="Services/TunnelSessionsClient.html" title="NgrokAPI::Services::TunnelSessionsClient (class)">TunnelSessionsClient</a></span>, <span class='object_link'><a href="Services/TunnelsClient.html" title="NgrokAPI::Services::TunnelsClient (class)">TunnelsClient</a></span>
     
   
 </p>
@@ -107,9 +107,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 24 19:20:29 2021 by
+  Generated on Thu Dec  2 18:48:49 2021 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.26 (ruby-3.0.1).
+  0.9.27 (ruby-3.0.1).
 </div>
 
     </div>

data/docs/NgrokAPI.html

@@ -6,7 +6,7 @@
 <title>
   Module: NgrokAPI
   
-    &mdash; Documentation by YARD 0.9.26
+    &mdash; Documentation by YARD 0.9.27
   
 </title>
 
@@ -79,7 +79,7 @@
   <dl>
     <dt>Defined in:</dt>
     <dd>lib/ngrokapi.rb<span class="defines">,<br />
-  lib/ngrokapi/error.rb,<br /> lib/ngrokapi/client.rb,<br /> lib/ngrokapi/version.rb,<br /> lib/ngrokapi/http_client.rb,<br /> lib/ngrokapi/models/api_key.rb,<br /> lib/ngrokapi/paged_iterator.rb,<br /> lib/ngrokapi/models/listable.rb,<br /> lib/ngrokapi/errors/not_found_error.rb,<br /> lib/ngrokapi/models/reserved_domain.rb,<br /> lib/ngrokapi/models/tls_certificate.rb,<br /> lib/ngrokapi/services/api_keys_client.rb,<br /> lib/ngrokapi/models/endpoint_configuration.rb,<br /> lib/ngrokapi/services/reserved_domains_client.rb,<br /> lib/ngrokapi/services/tls_certificates_client.rb,<br /> lib/ngrokapi/services/endpoint_configurations_client.rb</span>
+  lib/ngrokapi/error.rb,<br /> lib/ngrokapi/client.rb,<br /> lib/ngrokapi/version.rb,<br /> lib/ngrokapi/models/ref.rb,<br /> lib/ngrokapi/http_client.rb,<br /> lib/ngrokapi/models/tunnel.rb,<br /> lib/ngrokapi/models/api_key.rb,<br /> lib/ngrokapi/paged_iterator.rb,<br /> lib/ngrokapi/models/aws_auth.rb,<br /> lib/ngrokapi/models/aws_role.rb,<br /> lib/ngrokapi/models/listable.rb,<br /> lib/ngrokapi/models/ip_policy.rb,<br /> lib/ngrokapi/models/credential.rb,<br /> lib/ngrokapi/models/abuse_report.rb,<br /> lib/ngrokapi/models/event_source.rb,<br /> lib/ngrokapi/models/event_stream.rb,<br /> lib/ngrokapi/models/event_target.rb,<br /> lib/ngrokapi/models/agent_ingress.rb,<br /> lib/ngrokapi/models/endpoint_oidc.rb,<br /> lib/ngrokapi/models/endpoint_saml.rb,<br /> lib/ngrokapi/models/reserved_addr.rb,<br /> lib/ngrokapi/models/ip_policy_rule.rb,<br /> lib/ngrokapi/models/ip_restriction.rb,<br /> lib/ngrokapi/models/ssh_credential.rb,<br /> lib/ngrokapi/models/tunnel_session.rb,<br /> lib/ngrokapi/errors/not_found_error.rb,<br /> lib/ngrokapi/models/aws_credentials.rb,<br /> lib/ngrokapi/models/endpoint_o_auth.rb,<br /> lib/ngrokapi/models/reserved_domain.rb,<br /> lib/ngrokapi/models/tls_certificate.rb,<br /> lib/ngrokapi/models/endpoint_logging.rb,<br /> lib/ngrokapi/services/tunnels_client.rb,<br /> lib/ngrokapi/models/event_destination.rb,<br /> lib/ngrokapi/models/event_source_list.rb,<br /> lib/ngrokapi/services/api_keys_client.rb,<br /> lib/ngrokapi/models/endpoint_ip_policy.rb,<br /> lib/ngrokapi/models/event_subscription.rb,<br /> lib/ngrokapi/models/endpoint_mutual_tls.rb,<br /> lib/ngrokapi/models/endpoint_compression.rb,<br /> lib/ngrokapi/models/endpoint_saml_mutate.rb,<br /> lib/ngrokapi/models/event_source_replace.rb,<br /> lib/ngrokapi/models/event_target_kinesis.rb,<br /> lib/ngrokapi/models/ssh_host_certificate.rb,<br /> lib/ngrokapi/models/ssh_user_certificate.rb,<br /> lib/ngrokapi/services/credentials_client.rb,<br /> lib/ngrokapi/services/ip_policies_client.rb,<br /> lib/ngrokapi/models/abuse_report_hostname.rb,<br /> lib/ngrokapi/models/certificate_authority.rb,<br /> lib/ngrokapi/models/event_target_firehose.rb,<br /> lib/ngrokapi/models/tls_certificate_sa_ns.rb,<br /> lib/ngrokapi/models/endpoint_configuration.rb,<br /> lib/ngrokapi/models/endpoint_o_auth_google.rb,<br /> lib/ngrokapi/services/abuse_reports_client.rb,<br /> lib/ngrokapi/services/event_sources_client.rb,<br /> lib/ngrokapi/services/event_streams_client.rb,<br /> lib/ngrokapi/models/endpoint_logging_mutate.rb,<br /> lib/ngrokapi/models/endpoint_o_auth_git_hub.rb,<br /> lib/ngrokapi/services/reserved_addrs_client.rb,<br /> lib/ngrokapi/models/endpoint_circuit_breaker.rb,<br /> lib/ngrokapi/models/endpoint_o_auth_facebook.rb,<br /> lib/ngrokapi/models/endpoint_o_auth_provider.rb,<br /> lib/ngrokapi/models/endpoint_request_headers.rb,<br /> lib/ngrokapi/models/endpoint_tls_termination.rb,<br /> lib/ngrokapi/models/reserved_domain_cert_job.rb,<br /> lib/ngrokapi/services/agent_ingresses_client.rb,<br /> lib/ngrokapi/services/ip_policy_rules_client.rb,<br /> lib/ngrokapi/services/ip_restrictions_client.rb,<br /> lib/ngrokapi/services/ssh_credentials_client.rb,<br /> lib/ngrokapi/services/tunnel_sessions_client.rb,<br /> lib/ngrokapi/models/endpoint_ip_policy_mutate.rb,<br /> lib/ngrokapi/models/endpoint_o_auth_microsoft.rb,<br /> lib/ngrokapi/models/endpoint_response_headers.rb,<br /> lib/ngrokapi/models/ssh_certificate_authority.rb,<br /> lib/ngrokapi/services/reserved_domains_client.rb,<br /> lib/ngrokapi/services/tls_certificates_client.rb,<br /> lib/ngrokapi/models/endpoint_mutual_tls_mutate.rb,<br /> lib/ngrokapi/models/endpoint_webhook_validation.rb,<br /> lib/ngrokapi/models/reserved_domain_cert_policy.rb,<br /> lib/ngrokapi/models/reserved_domain_cert_status.rb,<br /> lib/ngrokapi/services/event_destinations_client.rb,<br /> lib/ngrokapi/models/event_target_cloudwatch_logs.rb,<br /> lib/ngrokapi/services/event_subscriptions_client.rb,<br /> lib/ngrokapi/services/endpoint_oidc_module_client.rb,<br /> lib/ngrokapi/services/endpoint_saml_module_client.rb,<br /> lib/ngrokapi/services/ssh_host_certificates_client.rb,<br /> lib/ngrokapi/services/ssh_user_certificates_client.rb,<br /> lib/ngrokapi/services/endpoint_o_auth_module_client.rb,<br /> lib/ngrokapi/services/certificate_authorities_client.rb,<br /> lib/ngrokapi/services/endpoint_configurations_client.rb,<br /> lib/ngrokapi/services/endpoint_logging_module_client.rb,<br /> lib/ngrokapi/services/endpoint_ip_policy_module_client.rb,<br /> lib/ngrokapi/services/endpoint_mutual_tls_module_client.rb,<br /> lib/ngrokapi/services/endpoint_compression_module_client.rb,<br /> lib/ngrokapi/services/ssh_certificate_authorities_client.rb,<br /> lib/ngrokapi/services/endpoint_circuit_breaker_module_client.rb,<br /> lib/ngrokapi/services/endpoint_request_headers_module_client.rb,<br /> lib/ngrokapi/services/endpoint_tls_termination_module_client.rb,<br /> lib/ngrokapi/services/endpoint_response_headers_module_client.rb,<br /> lib/ngrokapi/services/endpoint_webhook_validation_module_client.rb</span>
 </dd>
   </dl>
   
@@ -131,7 +131,7 @@
 
 </div>
         </dt>
-        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>0.1.0</span><span class='tstring_end'>&quot;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>0.9.0</span><span class='tstring_end'>&quot;</span></span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
       
     </dl>
   
@@ -147,9 +147,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri Sep 24 19:20:29 2021 by
+  Generated on Thu Dec  2 18:48:49 2021 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.26 (ruby-3.0.1).
+  0.9.27 (ruby-3.0.1).
 </div>
 
     </div>

data/docs/README

@@ -0,0 +1,94 @@
+# ngrok-api
+
+This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it
+easier to consume in Ruby.
+
+## Installation
+
+This library is published on [Rubygems](https://rubygems.org/gems/ngrok-api)
+
+```ruby
+gem install ngrok-api
+```
+
+## Quickstart
+
+Please consult the [documentation](https://ruby-api.docs.ngrok.com) for additional examples.
+
+```ruby
+require 'ngrokapi'
+client = NgrokAPI::Client.new(api_key: '<API KEY>')
+
+# Get an instance of the api_keys client and list all API keys
+keys_client = client.api_keys
+keys_client.list
+```
+
+## Automatic Paging
+
+The ngrok API pages all list resources but this library abstracts that away
+from you. All response objects from any ``list`` or ``list!`` methods return an object that
+implements an ``each`` method which will automatically fetch additional
+pages for you.
+
+```ruby
+require 'ngrokapi'
+client = NgrokAPI::Client.new(api_key: '<API KEY>')
+
+# list all api keys, transparently fetching additional
+# pages for you if necessary
+keys_client = client.api_keys
+keys_client.list.each do |key|
+  puts(key)
+end
+```
+
+## Instance Methods
+
+Instance methods like ``update`` and ``delete`` can be invoked on an instance of an
+API object itself as well as directly without needing to first fetch the object.
+
+```ruby
+require 'ngrokapi'
+client = NgrokAPI::Client.new(api_key: '<API KEY>')
+
+# update the metadata of a credential
+cred = client.credentials.get(id: 'cr_1kYyunEyn6XHHlqyMBLrj5nxkoz')
+cred.update(metadata: {server_name: 'giraffe-1'}.to_json)
+
+# or do it in single call
+cred = client.credentials.update(id: 'cr_1kYyunEyn6XHHlqyMBLrj5nxkoz', metadata: {server_name: 'giraffe-1'}.to_json)
+```
+
+## Bang Methods
+Most methods that interact with the API have a `!` counterpart. It raises an error when
+one is returned by the API.
+
+```ruby
+require 'ngrokapi'
+client = NgrokAPI::Client.new(api_key: '<API KEY>')
+
+# no error raised, even though it's a bad identifier
+# the error is simply returned
+cred = client.credentials.get(id: 'invalid')
+
+# this raises an NgrokAPI::Error
+cred = client.credentials.get!(id: 'invalid')
+```
+
+## Error Handling
+
+The ngrok API returns detailed information when an API call fails. Consult the
+section on errors for additional details.
+
+```ruby
+require 'ngrokapi'
+client = NgrokAPI::Client.new(api_key: '<API KEY>')
+
+begin
+    client.ip_policies.get!(id: 'invalid')
+rescue NgrokAPI::Error => e
+    puts(e)
+    puts(e.response.to_s)
+end
+```