added examples

examples/01_create_server.rhai

@@ -0,0 +1,56 @@
+// This script demonstrates how to create a new server using the Hetzner Cloud API.
+// It showcases the use of the `ServerBuilder` to configure the server's properties.
+
+// Initialize the Hetzner client with your API token.
+// It's recommended to use an environment variable for the token for security.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Create a new server builder.
+// The `new_server_builder` function requires three arguments:
+// 1. name: The name of the server (e.g., "my-server").
+// 2. server_type: The type of server (e.g., "cx11" for a basic server).
+// 3. image: The OS image to use (e.g., "ubuntu-22.04").
+let server_builder = new_server_builder("my-awesome-server", "cx22", "ubuntu-24.04");
+
+// The `ServerBuilder` provides several optional methods to customize the server.
+// You can chain these methods to configure the server as needed.
+
+// .with_location(location: string):
+//     Specifies the location to create the server in (e.g., "nbg1", "fsn1", "hel1").
+//     If not specified, the server will be created in a default location.
+// 
+// .with_datacenter(datacenter: string):
+//     Specifies the datacenter to create the server in (e.g., "nbg1-dc3", "fsn1-dc14").
+//     This is more specific than the location.
+//
+// .with_start_after_create(start: bool):
+//     Determines whether the server should be started immediately after creation.
+//     Defaults to `true`.
+//
+// .with_user_data(user_data: string):
+//     Provides cloud-init user data to configure the server on its first boot.
+//     This is useful for automating setup tasks.
+//     Example: "#cloud-config\nruncmd:\n  - [ ls, -l, / ]"
+//
+// .with_ssh_keys(ssh_keys: array):
+//     An array of SSH key IDs to associate with the server.
+//     If this method is not called, all available SSH keys in your account will be added.
+//     Example: .with_ssh_keys([12345, 67890])
+
+// Example of chaining optional builder methods:
+let server_builder = server_builder
+    .with_location("fsn1")
+    .with_user_data("#cloud-config\nruncmd:\n  - [ apt-get, update ]\n  - [ apt-get, install, -y, htop ]");
+
+// Create the server using the configured builder.
+let response = client.create_server(server_builder);
+
+// Print the details of the server creation response.
+print(`Server creation initiated for: ${response.name}`);
+print(`  ID: ${response.id}`);
+print(`  Status: ${response.status}`);
+if response.root_password != "" {
+    print(`  Root Password: ${response.root_password}`);
+} else {
+    print("  Root Password: Not set (SSH key was provided)");
+}

examples/02_list_servers.rhai

@@ -0,0 +1,11 @@
+// This script demonstrates how to list all servers in your Hetzner Cloud project.
+
+// Initialize the Hetzner client with your API token.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Retrieve the list of all servers.
+print("Listing all servers...");
+let servers = client.list_servers();
+
+// The `show_table` method formats the server list into a user-friendly table.
+print(servers.show_table());

examples/03_get_server_details.rhai

@@ -0,0 +1,15 @@
+// This script demonstrates how to retrieve detailed information for a specific server.
+
+// Initialize the Hetzner client with your API token.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Replace this with the ID of the server you want to inspect.
+// You can get the server ID by listing all servers (see 02_list_servers.rhai).
+let server_id = 104298257; // FIXME: Replace with your own ID
+
+// Get the server object by its ID.
+print(`Fetching details for server with ID: ${server_id}...`);
+let server = client.get_server(server_id);
+
+// The `show_details` method provides a comprehensive overview of the server's properties.
+print(server.show_details());

examples/04_server_actions.rhai

@@ -0,0 +1,43 @@
+// This script demonstrates how to perform various actions on a server,
+// such as rebooting, resetting, and managing rescue mode.
+
+// Initialize the Hetzner client with your API token.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Replace this with the ID of the server you want to manage.
+let server_id = 1234567; // FIXME: Replace with a real server ID
+
+// --- Reboot Server ---
+// A soft reboot is attempted first. If it doesn't succeed, a hard reset is performed.
+print(`Rebooting server with ID: ${server_id}...`);
+client.reboot(server_id);
+print("Reboot command sent.");
+
+// --- Reset Server ---
+// This is equivalent to a hard reset (power cycle).
+// print(`Resetting server with ID: ${server_id}...`);
+// client.reset(server_id);
+// print("Reset command sent.");
+
+// --- Enable Rescue Mode ---
+// Enables rescue mode for a server. This is useful for maintenance and recovery.
+// The `enable_rescue_mode` function can be called in three ways:
+
+// 1. With only the server ID:
+//    This will enable rescue mode and add all SSH keys from your account to the rescue system.
+//    let root_password = client.enable_rescue_mode(server_id);
+
+// 2. With a single SSH key ID:
+//    let ssh_key_id = 98765; // FIXME: Replace with your SSH key ID
+//    let root_password = client.enable_rescue_mode(server_id, ssh_key_id);
+
+// 3. With an array of SSH key IDs:
+// let ssh_key_ids = [98765, 54321]; // FIXME: Replace with your SSH key IDs
+// let root_password = client.enable_rescue_mode(server_id, ssh_key_ids);
+// print(`Rescue mode enabled. Root password: ${root_password}`);
+
+// --- Disable Rescue Mode ---
+// Disables rescue mode and reboots the server back into its normal OS.
+// print(`Disabling rescue mode for server ID: ${server_id}...`);
+// client.disable_rescue_mode(server_id);
+// print("Rescue mode disabled.");

examples/05_list_ssh_keys.rhai

@@ -0,0 +1,11 @@
+// This script demonstrates how to list all SSH keys in your Hetzner Cloud project.
+
+// Initialize the Hetzner client with your API token.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Retrieve the list of all SSH keys.
+print("Listing all SSH keys...");
+let ssh_keys = client.list_ssh_keys();
+
+// The `show_table` method formats the SSH key list into a user-friendly table.
+print(ssh_keys.show_table());

examples/06_list_images.rhai

@@ -0,0 +1,58 @@
+// This script demonstrates how to list available images using various filters.
+// It showcases the `ListImagesParamsBuilder` for customizing the query.
+
+// Initialize the Hetzner client with your API token.
+let client = new_hetzner_client(get_env("HETZNER_API_TOKEN"));
+
+// Create a new builder for listing images.
+// You can use this builder to filter and sort the results.
+let params_builder = new_list_images_params_builder();
+
+// The `ListImagesParamsBuilder` provides several optional methods:
+//
+// .with_status(status: string):
+//     Filters images by status. Can be "available" or "creating".
+//
+// .with_type(type: string):
+//     Filters images by type. Can be "system", "snapshot", or "backup".
+//
+// .with_sort(sort: string):
+//     Sorts the results. Can be "id", "id:asc", "id:desc", "name", "name:asc",
+//     "name:desc", "created", "created:asc", "created:desc".
+//
+// .with_bound_to(server_id: string):
+//     Filters images bound to a specific server ID.
+//
+// .with_include_deprecated(include: bool):
+//     Determines whether to include deprecated images. Defaults to `false`.
+//
+// .with_name(name: string):
+//     Filters images by name.
+//
+// .with_label_selector(selector: string):
+//     Filters by label selector.
+//
+// .with_architecture(architecture: string):
+//     Filters by architecture. Can be "x86" or "arm".
+
+// Example: List all available snapshots, sorted by creation date.
+let params = params_builder
+    .with_type("snapshot")
+    .with_status("available")
+    .with_sort("created:desc");
+
+// List the images using the configured parameters.
+print("Listing all available snapshots...");
+let images = client.list_images(params);
+
+// Display the results in a table.
+print(images.show_table());
+
+// Example 2: Find a specific system image by name.
+let params2 = new_list_images_params_builder()
+    .with_type("system")
+    .with_name("ubuntu-24.04");
+
+print("\nFinding Ubuntu 24.04 image...");
+let ubuntu_image = client.list_images(params2);
+print(ubuntu_image.show_table());