add client abstraction with headers, update readme

README.md

···
 
 Squall parses `.gql` files in your project, introspects your GraphQL endpoint, and generates fully type-safe Gleam code with decoders, eliminating runtime errors and keeping your GraphQL queries in sync with your schema.
 
+> **⚠️ Warning**: This project is in early development and may contain bugs. Use at your own risk.
+
 ## Features
 
-- ✅ **Type-Safe**: Generated code is fully typed based on your GraphQL schema
-- ✅ **Convention-based**: Drop `.gql` files in `src/**/graphql/` directories
-- ✅ **Zero Configuration**: No config files needed
-- ✅ **Schema Introspection**: Automatically fetches types from your GraphQL endpoint
-- ✅ **Full GraphQL Support**: Queries, Mutations, and Subscriptions
-- ✅ **Test-Driven**: Built with TDD, 38+ passing tests
-- ✅ **Gleam-First**: Generates idiomatic Gleam code
+- Type-safe code generation from GraphQL schema
+- Convention over configuration - `.gql` files in `src/**/graphql/` directories
+- Schema introspection from GraphQL endpoints
+- Supports queries, mutations, and subscriptions
+- Client abstraction with authentication and custom headers
+- Multiple endpoint support
 
 ## Installation
 
···
 
 ```toml
 [dependencies]
-squall = "1.0.0"
+squall = "0.1.0"
 ```
 
 ## Quick Start
···
 ### 3. Use the generated code
 
 ```gleam
+import squall
 import my_app/graphql/get_character
 
 pub fn main() {
-  let endpoint = "https://rickandmortyapi.com/graphql"
+  // Create a client
+  let client = squall.new_client(
+    endpoint: "https://rickandmortyapi.com/graphql",
+    headers: []
+  )
 
-  case get_character.get_character(endpoint, "1") {
+  // Use the generated function
+  case get_character.get_character(client: client, id: "1") {
     Ok(response) -> {
-      io.println("Character: " <> response.name)
+      io.println("Character: " <> response.character.name)
     }
     Error(err) -> {
       io.println("Error: " <> err)
···
 }
 ```
 
+## Creating a Client
+
+Squall uses a client abstraction to manage your GraphQL endpoint and headers (including authentication):
+
+```gleam
+import squall
+
+// Create a client with custom headers
+let client = squall.new_client(
+  endpoint: "https://api.example.com/graphql",
+  headers: [
+    #("Authorization", "Bearer your-api-token-here"),
+    #("X-Custom-Header", "value")
+  ]
+)
+
+// Or use the convenience function for bearer token auth
+let client = squall.new_client_with_auth(
+  endpoint: "https://api.example.com/graphql",
+  token: "your-api-token-here"
+)
+
+// For public APIs with no authentication
+let client = squall.new_client(
+  endpoint: "https://rickandmortyapi.com/graphql",
+  headers: []
+)
+```
+
 ## How It Works
 
 Squall follows a simple workflow:
···
 }
 
 pub fn get_user(
-  endpoint: String,
+  client: squall.Client,
   id: String,
 ) -> Result(GetUserResponse, String) {
   // HTTP request + JSON decoding implementation
···
 - **`codegen`**: Generates Gleam code
 - **`error`**: Comprehensive error handling
 
-## Comparison with Squirrel
-
-Squall is inspired by [squirrel](https://github.com/giacomocavalieri/squirrel) but for GraphQL instead of SQL:
-
-| Feature | Squirrel (SQL) | Squall (GraphQL) |
-|---------|----------------|------------------|
-| Query Language | SQL | GraphQL |
-| Type Source | PostgreSQL | GraphQL Schema |
-| File Pattern | `sql/*.sql` | `graphql/*.gql` |
-| Type Safety | ✅ | ✅ |
-| Zero Config | ✅ | ✅ |
-| Convention-based | ✅ | ✅ |
-
 ## Development
 
 ### Running Tests
···
 - [x] Subscription support
 - [x] Type-safe code generation
 - [x] Schema introspection
-- [ ] HTTP client implementation
+- [x] Client abstraction with headers/authentication
+- [x] Multiple endpoint support
 - [ ] Fragment support
 - [ ] Directive handling
 - [ ] Custom scalar mapping
-- [ ] Multiple endpoint support
 
 ## Contributing
 
···
 ## License
 
 Apache-2.0
-
-## Acknowledgments
-
-- Inspired by [squirrel](https://github.com/giacomocavalieri/squirrel) by Giacomo Cavalieri
-- Built with [Gleam](https://gleam.run/)
-- Tested with the [Rick and Morty API](https://rickandmortyapi.com/graphql)
-
----
-
-Made with 🌊 and Gleam

birdie_snapshots/mutation_function_generation.accepted

···
 ---
 version: 1.2.0
 title: Mutation function generation
-file: ./test/codegen_test.gleam
-test_name: generate_mutation_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type User {
   User(id: String, name: String)
···
   }
 }
 
-pub fn create_user(endpoint: String, name: String) -> Result(CreateUserResponse, String) {
+pub fn create_user(client: squall.Client, name: String) -> Result(CreateUserResponse, String) {
   let query =
     "mutation CreateUser($name: String!) { createUser(name: $name) { id name } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_inline_array_arguments.accepted

···
 ---
 version: 1.2.0
 title: Query with inline array arguments
-file: ./test/codegen_test.gleam
-test_name: generate_inline_array_arguments_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type Episode {
   Episode(id: String, name: String)
···
   }
 }
 
-pub fn get_episodes(endpoint: String) -> Result(GetEpisodesResponse, String) {
+pub fn get_episodes(client: squall.Client) -> Result(GetEpisodesResponse, String) {
   let query =
     "query GetEpisodes { episodesByIds(ids: [1, 2, 3]) { id name } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_inline_object_arguments.accepted

···
 ---
 version: 1.2.0
 title: Query with inline object arguments
-file: ./test/codegen_test.gleam
-test_name: generate_inline_object_arguments_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type CharactersResult {
   CharactersResult(results: Option(List(Character)))
···
   }
 }
 
-pub fn get_characters(endpoint: String) -> Result(GetCharactersResponse, String) {
+pub fn get_characters(client: squall.Client) -> Result(GetCharactersResponse, String) {
   let query =
     "query GetCharacters { characters(filter: { name: \"rick\", status: \"alive\" }) { results { id name } } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_inline_scalar_arguments.accepted

···
 ---
 version: 1.2.0
 title: Query with inline scalar arguments
-file: ./test/codegen_test.gleam
-test_name: generate_inline_scalar_arguments_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type Character {
   Character(id: String, name: String)
···
   }
 }
 
-pub fn get_character(endpoint: String) -> Result(GetCharacterResponse, String) {
+pub fn get_character(client: squall.Client) -> Result(GetCharacterResponse, String) {
   let query =
     "query GetCharacter { character(id: 1) { id name } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_multiple_root_fields_and_mixed_arguments.accepted

···
 ---
 version: 1.2.0
 title: Query with multiple root fields and mixed arguments
-file: ./test/codegen_test.gleam
-test_name: generate_multiple_root_fields_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type CharactersResult {
   CharactersResult(info: Option(Info), results: Option(List(Character)))
···
   }
 }
 
-pub fn multi_query(endpoint: String) -> Result(MultiQueryResponse, String) {
+pub fn multi_query(client: squall.Client) -> Result(MultiQueryResponse, String) {
   let query =
     "query MultiQuery { characters(page: 2, filter: { name: \"rick\" }) { info { count } results { name } } location(id: 1) { id } episodesByIds(ids: [1, 2]) { id } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_nested_types_generation.accepted

···
 ---
 version: 1.2.0
 title: Query with nested types generation
-file: ./test/codegen_test.gleam
-test_name: generate_query_with_nested_types_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type Character {
   Character(id: String, name: String, status: String)
···
   }
 }
 
-pub fn get_character(endpoint: String, id: String) -> Result(GetCharacterResponse, String) {
+pub fn get_character(client: squall.Client, id: String) -> Result(GetCharacterResponse, String) {
   let query =
     "query GetCharacter($id: ID!) { character(id: $id) { id name status } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/query_with_variables_function_generation.accepted

···
 ---
 version: 1.2.0
 title: Query with variables function generation
-file: ./test/codegen_test.gleam
-test_name: generate_query_with_variables_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type User {
   User(id: String, name: Option(String))
···
   }
 }
 
-pub fn get_user(endpoint: String, id: String) -> Result(GetUserResponse, String) {
+pub fn get_user(client: squall.Client, id: String) -> Result(GetUserResponse, String) {
   let query =
     "query GetUser($id: ID!) { user(id: $id) { id name } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/simple_query_function_generation.accepted

···
 ---
 version: 1.2.0
 title: Simple query function generation
-file: ./test/codegen_test.gleam
-test_name: generate_simple_query_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type User {
   User(id: String, name: Option(String))
···
   }
 }
 
-pub fn get_user(endpoint: String) -> Result(GetUserResponse, String) {
+pub fn get_user(client: squall.Client) -> Result(GetUserResponse, String) {
   let query =
     "query GetUser { user { id name } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

birdie_snapshots/type_with_reserved_keywords.accepted

···
 ---
 version: 1.2.0
 title: Type with reserved keywords
-file: ./test/codegen_test.gleam
-test_name: generate_with_reserved_keywords_test
 ---
 import gleam/dynamic
 import gleam/http
 import gleam/http/request
 import gleam/httpc
 import gleam/json
+import gleam/list
 import gleam/option.{type Option}
 import gleam/result
+import squall
 
 pub type Item {
   Item(
···
   }
 }
 
-pub fn get_item(endpoint: String) -> Result(GetItemResponse, String) {
+pub fn get_item(client: squall.Client) -> Result(GetItemResponse, String) {
   let query =
     "query GetItem { item { id type case let } }"
   let variables =
···
   let body =
     json.object([#("query", json.string(query)), #("variables", variables)])
   use req <- result.try(
-    request.to(endpoint)
+    request.to(client.endpoint)
     |> result.map_error(fn(_) { "Invalid endpoint URL" }),
   )
   let req =
···
     |> request.set_method(http.Post)
     |> request.set_body(json.to_string(body))
     |> request.set_header("content-type", "application/json")
+  let req =
+    list.fold(client.headers, req, fn(r, header) {
+      request.set_header(r, header.0, header.1)
+    })
   use resp <- result.try(
     httpc.send(req)
     |> result.map_error(fn(_) { "HTTP request failed" }),

src/squall.gleam

···
 import squall/internal/parser
 import squall/internal/schema
 
+/// A GraphQL client with endpoint and headers configuration
+pub type Client {
+  Client(endpoint: String, headers: List(#(String, String)))
+}
+
+/// Create a new GraphQL client with custom headers
+pub fn new_client(endpoint: String, headers: List(#(String, String))) -> Client {
+  Client(endpoint: endpoint, headers: headers)
+}
+
+/// Create a new GraphQL client with bearer token authentication
+pub fn new_client_with_auth(endpoint: String, token: String) -> Client {
+  Client(endpoint: endpoint, headers: [#("Authorization", "Bearer " <> token)])
+}
+
 pub fn main() {
   case argv.load().arguments {
     ["generate", endpoint] -> generate(endpoint)

src/squall/internal/codegen.gleam

···
     "import gleam/http/request",
     "import gleam/httpc",
     "import gleam/json",
+    "import gleam/list",
     "import gleam/option.{type Option}",
     "import gleam/result",
+    "import squall",
   ]
 
   import_lines
···
 
   // Build parameter list as documents
   let param_docs = case variables {
-    [] -> [doc.from_string("endpoint: String")]
+    [] -> [doc.from_string("client: squall.Client")]
     vars -> {
       let var_param_docs =
         vars
···
         })
         |> list.filter_map(fn(r) { r })
 
-      [doc.from_string("endpoint: String"), ..var_param_docs]
+      [doc.from_string("client: squall.Client"), ..var_param_docs]
     }
   }
 
···
       doc.from_string("use req <- result.try("),
       doc.concat([
         doc.line,
-        call_doc("request.to", [doc.from_string("endpoint")]),
+        call_doc("request.to", [doc.from_string("client.endpoint")]),
         doc.line,
         doc.from_string("|> result.map_error(fn(_) { \"Invalid endpoint URL\" }),"),
       ])
···
         doc.from_string("|> request.set_body(json.to_string(body))"),
         doc.line,
         doc.from_string("|> request.set_header(\"content-type\", \"application/json\")"),
+      ]),
+    ),
+    let_var(
+      "req",
+      doc.concat([
+        doc.from_string("list.fold(client.headers, req, fn(r, header) {"),
+        doc.line,
+        doc.from_string("  request.set_header(r, header.0, header.1)"),
+        doc.line,
+        doc.from_string("})"),
       ]),
     ),
     doc.concat([