feat: add regions api (#9)

* add regions

* Update src/lib/regions.ts

Co-authored-by: Han Qiao <[email protected]>

* Update src/lib/types.ts

Co-authored-by: Han Qiao <[email protected]>

* dep

* dep

* more work on types

* rerun npm gen:types

* Revert "rerun npm gen:types"

This reverts commit 0980180.

* chore: update mock response for unit tests

---------

Co-authored-by: Han Qiao <[email protected]>
Co-authored-by: Qiao Han <[email protected]>

Author: nicholasoxford

__tests__/regions.test.ts

@@ -0,0 +1,40 @@
+import nock from 'nock'
+import { describe, it, expect } from '@jest/globals'
+import { FLY_API_GRAPHQL } from '../src/client'
+import { createClient } from '../src/main'
+
+const fly = createClient(process.env.FLY_API_TOKEN || 'test-token')
+
+describe('regions', () => {
+  it('get regions', async () => {
+    const mockResponse = {
+      data: {
+        platform: {
+          requestRegion: 'sin',
+          regions: [
+            {
+              name: 'Amsterdam, Netherlands',
+              code: 'ams',
+              latitude: 52.374342,
+              longitude: 4.895439,
+              gatewayAvailable: true,
+              requiresPaidPlan: false,
+            },
+            // Add more mock regions as needed
+          ],
+        },
+      },
+    }
+
+    nock(FLY_API_GRAPHQL).post('/graphql').reply(200, mockResponse)
+
+    const data = await fly.Regions.getRegions()
+    console.dir(data, { depth: 5 })
+
+    // Optionally, add assertions to verify the response
+    expect(data).toBeDefined()
+    expect(data.platform).toBeDefined()
+    expect(data.platform.regions).toBeInstanceOf(Array)
+    // Add more assertions as needed
+  })
+})

src/client.ts

@@ -5,6 +5,7 @@ import { Network } from './lib/network'
 import { Organization } from './lib/organization'
 import { Secret } from './lib/secret'
 import { Volume } from './lib/volume'
+import { Regions } from './lib/regions'
 
 export const FLY_API_GRAPHQL = 'https://api.fly.io'
 export const FLY_API_HOSTNAME = 'https://api.machines.dev'
@@ -36,6 +37,7 @@ class Client {
   private apiKey: string
   App: App
   Machine: Machine
+  Regions: Regions
   Network: Network
   Organization: Organization
   Secret: Secret
@@ -51,6 +53,7 @@ class Client {
     this.App = new App(this)
     this.Machine = new Machine(this)
     this.Network = new Network(this)
+    this.Regions = new Regions(this)
     this.Organization = new Organization(this)
     this.Secret = new Secret(this)
     this.Volume = new Volume(this)

src/lib/regions.ts

@@ -0,0 +1,49 @@
+import Client from '../client'
+
+interface RegionResponse {
+  name: string
+  code: string
+  latitude: number
+  longitude: number
+  gatewayAvailable: boolean
+  requiresPaidPlan: boolean
+}
+
+interface PlatformResponse {
+  requestRegion: string
+  regions: RegionResponse[]
+}
+
+export interface GetRegionsOutput {
+  platform: PlatformResponse
+}
+
+// Ref: https://github.com/superfly/flyctl/blob/master/api/resource_platform.go
+const getRegionsQuery = `query {
+  platform {
+    requestRegion
+    regions {
+      name
+      code
+      latitude
+      longitude
+      gatewayAvailable
+      requiresPaidPlan
+    }
+  }
+}`
+
+export class Regions {
+  private client: Client
+
+  constructor(client: Client) {
+    this.client = client
+  }
+
+  async getRegions(): Promise<GetRegionsOutput> {
+    return this.client.gqlPostOrThrow({
+      query: getRegionsQuery,
+      variables: {},
+    })
+  }
+}

src/lib/types.ts

@@ -10,6 +10,7 @@
  */
 
 export interface App {
+  id?: string
   name?: string
   organization?: Organization
   status?: string
@@ -24,6 +25,7 @@ export interface CheckStatus {
 
 export interface CreateAppRequest {
   app_name?: string
+  app_role_id?: string
   network?: string
   org_slug?: string
 }
@@ -34,9 +36,13 @@ export interface CreateLeaseRequest {
 }
 
 export interface CreateMachineRequest {
+  /** An object defining the Machine configuration */
   config?: ApiMachineConfig
   lease_ttl?: number
+  lsvd?: boolean
+  /** Unique name for this Machine. If omitted, one is generated for you */
   name?: string
+  /** The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). */
   region?: string
   skip_launch?: boolean
   skip_service_registration?: boolean
@@ -53,12 +59,16 @@ export interface CreateVolumeRequest {
   size_gb?: number
   /** restore from snapshot */
   snapshot_id?: string
+  snapshot_retention?: number
   /** fork from remote volume */
   source_volume_id?: string
 }
 
 export interface ErrorResponse {
+  /** Deprecated */
+  details?: any
   error?: string
+  status?: MainStatusCode
 }
 
 export interface ExtendVolumeRequest {
@@ -87,9 +97,12 @@ export interface Lease {
   nonce?: string
   /** Owner is the user identifier which acquired the Lease. */
   owner?: string
+  /** Machine version */
+  version?: string
 }
 
 export interface ListApp {
+  id?: string
   machine_count?: number
   name?: string
   network?: any
@@ -171,15 +184,23 @@ export interface StopRequest {
 }
 
 export interface UpdateMachineRequest {
+  /** An object defining the Machine configuration */
   config?: ApiMachineConfig
   current_version?: string
   lease_ttl?: number
+  lsvd?: boolean
+  /** Unique name for this Machine. If omitted, one is generated for you */
   name?: string
+  /** The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). */
   region?: string
   skip_launch?: boolean
   skip_service_registration?: boolean
 }
 
+export interface UpdateVolumeRequest {
+  snapshot_retention?: number
+}
+
 export interface Volume {
   attached_alloc_id?: string
   attached_machine_id?: string
@@ -194,6 +215,7 @@ export interface Volume {
   name?: string
   region?: string
   size_gb?: number
+  snapshot_retention?: number
   state?: string
   zone?: string
 }
@@ -203,73 +225,81 @@ export interface VolumeSnapshot {
   digest?: string
   id?: string
   size?: number
+  status?: string
 }
 
 export interface ApiDNSConfig {
   skip_registration?: boolean
 }
 
+/** A file that will be written to the Machine. One of RawValue or SecretName must be set. */
 export interface ApiFile {
   /**
    * GuestPath is the path on the machine where the file will be written and must be an absolute path.
-   * i.e. /full/path/to/file.json
+   * For example: /full/path/to/file.json
    */
   guest_path?: string
-  /** RawValue containts the base64 encoded string of the file contents. */
+  /** The base64 encoded string of the file contents. */
   raw_value?: string
-  /** SecretName is the name of the secret that contains the base64 encoded file contents. */
+  /** The name of the secret that contains the base64 encoded file contents. */
   secret_name?: string
 }
 
 export interface ApiHTTPOptions {
   compress?: boolean
+  h2_backend?: boolean
   response?: ApiHTTPResponseOptions
 }
 
 export interface ApiHTTPResponseOptions {
   headers?: Record<string, any>
 }
 
+/** An optional object that defines one or more named checks. The key for each check is the check name. */
 export interface ApiMachineCheck {
+  /** The time to wait after a VM starts before checking its health */
   grace_period?: string
   headers?: ApiMachineHTTPHeader[]
+  /** The time between connectivity checks */
   interval?: string
+  /** For http checks, the HTTP method to use to when making the request */
   method?: string
+  /** For http checks, the path to send the request to */
   path?: string
+  /** The port to connect to, often the same as internal_port */
   port?: number
+  /** For http checks, whether to use http or https */
   protocol?: string
+  /** The maximum time a connection can take before being reported as failing its health check */
   timeout?: string
+  /** If the protocol is https, the hostname to use for TLS certificate validation */
   tls_server_name?: string
+  /** For http checks with https protocol, whether or not to verify the TLS certificate */
   tls_skip_verify?: boolean
+  /** tcp or http */
   type?: string
 }
 
 export interface ApiMachineConfig {
+  /** Optional boolean telling the Machine to destroy itself once it’s complete (default false) */
   auto_destroy?: boolean
   checks?: Record<string, ApiMachineCheck>
   /** Deprecated: use Service.Autostart instead */
   disable_machine_autostart?: boolean
   dns?: ApiDNSConfig
-  /**
-   * Fields managed from fly.toml
-   * If you add anything here, ensure appconfig.Config.ToMachine() is updated
-   */
+  /** An object filled with key/value pairs to be set as environment variables */
   env?: Record<string, string>
   files?: ApiFile[]
   guest?: ApiMachineGuest
-  host_dedication_id?: string
-  /** Set by fly deploy or fly machines commands */
+  /** The docker image to run */
   image?: string
   init?: ApiMachineInit
   metadata?: Record<string, string>
   metrics?: ApiMachineMetrics
   mounts?: ApiMachineMount[]
   processes?: ApiMachineProcess[]
+  /** The Machine restart policy defines whether and how flyd restarts a Machine after its main process exits. See https://fly.io/docs/machines/guides-examples/machine-restart-policy/. */
   restart?: ApiMachineRestart
-  /**
-   * The following fields can only be set or updated by `fly machines run|update` commands
-   * "fly deploy" must preserve them, if you add anything here, ensure it is propagated on deploys
-   */
   schedule?: string
   services?: ApiMachineService[]
   /** Deprecated: use Guest instead */
@@ -286,13 +316,17 @@ export interface ApiMachineConfig {
 export interface ApiMachineGuest {
   cpu_kind?: string
   cpus?: number
-  gpus?: number
+  gpu_kind?: string
+  host_dedication_id?: string
   kernel_args?: string[]
   memory_mb?: number
 }
 
+/** For http checks, an array of objects with string field Name and array of strings field Values. The key/value pairs specify header and header values that will get passed with the check call. */
 export interface ApiMachineHTTPHeader {
+  /** The header name */
   name?: string
+  /** The header value */
   values?: string[]
 }
 
@@ -311,10 +345,13 @@ export interface ApiMachineMetrics {
 }
 
 export interface ApiMachineMount {
+  add_size_gb?: number
   encrypted?: boolean
+  extend_threshold_percent?: number
   name?: string
   path?: string
   size_gb?: number
+  size_gb_limit?: number
   volume?: string
 }
 
@@ -337,10 +374,16 @@ export interface ApiMachineProcess {
   user?: string
 }
 
+/** The Machine restart policy defines whether and how flyd restarts a Machine after its main process exits. See https://fly.io/docs/machines/guides-examples/machine-restart-policy/. */
 export interface ApiMachineRestart {
-  /** MaxRetries is only relevant with the on-failure policy. */
+  /** When policy is on-failure, the maximum number of times to attempt to restart the Machine before letting it stop. */
   max_retries?: number
-  policy?: string
+  /**
+   * * no - Never try to restart a Machine automatically when its main process exits, whether that’s on purpose or on a crash.
+   * * always - Always restart a Machine automatically and never let it enter a stopped state, even when the main process exits cleanly.
+   * * on-failure - Try up to MaxRetries times to automatically restart the Machine if it exits with a non-zero exit code. Default when no explicit policy is set, and for Machines with schedules.
+   */
+  policy?: ApiMachineRestartPolicyEnum
 }
 
 export interface ApiMachineService {
@@ -382,6 +425,11 @@ export interface ApiTLSOptions {
   versions?: string[]
 }
 
+export enum MainStatusCode {
+  Unknown = 'unknown',
+  CapacityErr = 'insufficient_capacity',
+}
+
 export enum SignalRequestSignalEnum {
   SIGABRT = 'SIGABRT',
   SIGALRM = 'SIGALRM',
@@ -398,9 +446,20 @@ export enum SignalRequestSignalEnum {
   SIGUSR1 = 'SIGUSR1',
 }
 
+/**
+ * * no - Never try to restart a Machine automatically when its main process exits, whether that’s on purpose or on a crash.
+ * * always - Always restart a Machine automatically and never let it enter a stopped state, even when the main process exits cleanly.
+ * * on-failure - Try up to MaxRetries times to automatically restart the Machine if it exits with a non-zero exit code. Default when no explicit policy is set, and for Machines with schedules.
+ */
+export enum ApiMachineRestartPolicyEnum {
+  No = 'no',
+  Always = 'always',
+  OnFailure = 'on-failure',
+}
+
 export interface AppsListParams {
   /** The org slug, or 'personal', to filter apps */
-  org_slug?: string
+  org_slug: string
 }
 
 export interface MachinesListParams {