fix merge conflicts

.gitignore

@@ -6,4 +6,4 @@ Manifest.toml
 .vscode
 .envrc
 test/add_records.json
-LocalPreferences.toml
+LocalPreferences.toml

Project.toml

@@ -14,6 +14,7 @@ ReTest = "e0db7c4e-2690-44b9-bad6-7687da720f89"
 [compat]
 HTTP = "0.8, 0.9, 1"
 JSON3 = "1"
+Preferences = "1.4.3"
 ProgressMeter = "1"
 ReTest = "0.3"
 julia = "1.6"

docs/src/index.md

@@ -38,19 +38,21 @@ personal access token (PAT).
    You should now use Personal Access Tokens.
    [See here](https://support.airtable.com/docs/airtable-api-key-deprecation-notice) for more info.
 
+To obtain your API key, go to the ["create tokens" page of the developer hub](https://airtable.com/create/tokens)
+and click on the "Create new token" button.
 
-To obtain your, go to the [create tokens](https://airtable.com/create/tokens) page,
-then click "create new token".
+![Create airtable token](img/create-token-1.png)
 
-![Get airtable Personal Access Token](img/create.png)
+You need to give the token a "scope" (eg, what can you do with this token)
+and "access" (eg which bases can it work on).
+For scope, you'll generally want at least `data.records:read`,
+and if you want to make changes, you'll need `data.records:write`.
 
-Give your token a name,
-then provide the required scopes (eg ability to read or write records)
-and access (you can provide access to only a single base, or a whole workspace).
+Once you've done this and given the key a name, click "Create token".
+The key will only be displayed once, so save it somewhere.
 
-![Provide permissions](img/scope.png)
+![Create airtable token 2](img/create-token-2.png)
 
-![Provide permissions](img/access.png)
 
 !!! note
    Once you click "done", you will not be able to retrieve your PAT.
@@ -63,22 +65,21 @@ This can be done explicitly by passing a PAT as a string to the `Credential()` c
 
 ```julia-repl
 julia> cred = Airtable.Credential("patfh3gwMkFASf6Ue.0103ff9d0148e6b573582e513a7f1dcb76300e52b67463c99d9c499f46f9fa98")
-Airtable.Credential(<secrets>)
+Airtable.Credential("patfh3gwMkFASf6Ue")
 
 julia> Airtable.get(cred, #...)
 ```
 
 Alternatively,
-you can use `Preferences.jl` to set
-`"readonly_pat"` or `"readwrite_pat"`,
+you can use `Preferences.jl` to set `"PAT"`
 or set the environmental variable `"AIRTABLE_KEY"`.
 
 Eg.
 
 ```julia-repl
 using Preferences
 
-julia> set_preferences!(Airtable, "readwrite_pat"=>"<REDACTED>")
+julia> set_preferences!(Airtable, "PAT"=>patfh3gwMkFASf6Ue.0103ff9d0148e6b573582e513a7f1dcb76300e52b67463c99d9c499f46f9fa98)
 
 julia> julia> cred = Airtable.Credential()
 Airtable.Credential(<secrets>)
@@ -97,10 +98,15 @@ and will use (in order)
 2. "readonly_pat" set in `Preferences`
 3. the environmental variable `AIRTABLE_KEY`
 
+
 ```@docs
+set_pat
 Credential
 ```
 
+It is recommended that you use `LocalPreferences.toml`
+or the environmental variable,
+since many functions can use that by default instead of requiring that you pass it as an argument.
 
 ### [Base ID](@id baseid)
 

src/Airtable.jl

@@ -10,6 +10,7 @@ using HTTP
 using JSON3
 using Preferences: @load_preference, @set_preferences!
 using ProgressMeter
+using Preferences
 using ReTest
 
 const API_VERSION = "v0"

src/auth.jl

@@ -2,6 +2,7 @@
      Credential(; token)
      
 A credential object for Airtable.
+<<<<<<< HEAD
 If the token is not provided,
 it will be read from, 
 
@@ -13,30 +14,90 @@ Read the [Airtable docs](https://support.airtable.com/docs/airtable-api-key-depr
 for more info on personal access tokens,
 or go to [Airtable account settings](https://airtable.com/create/tokens) 
 to aquire your personal access token(s).
+||||||| 764d019
+If the api_key or api_token are not provided,
+they will be read from the `AIRTABLE_KEY` environment variable.
+Go to [Airtable account settings](https://airtable.com/account) 
+to aquire your credentials.
+=======
+If a Personal Access Token (PAT) is not provided,
+it will be read from your `LocalPreferences.toml` file
+using the key "PAT", or the `AIRTABLE_KEY` environment variable.
+Go to [Airtable developer hub](https://airtable.com/create/token) 
+to aquire your PAT.
+
+See also: [`set_pat`](@ref)
+>>>>>>> pat
 
 ```jldoctest; setup = :(using Airtable)
+<<<<<<< HEAD
 # with local preferences set, or after running `export AIRTABLE_KEY=<api key>` in the shell
+||||||| 764d019
+# after running `export AIRTABLE_KEY=<api key>` in the shell
+=======
+# after running `Airtable.set_pat("patfh3gwMkFASf6Ue.<obscured>")`
+>>>>>>> pat
 julia> key = Airtable.Credential()
-Airtable.Credential(<secrets>)
+Airtable.Credential("patfh3gwMkFASf6Ue")
 ```
 
 """
 struct Credential
     token::String
 end
 
+<<<<<<< HEAD
 
 function Credential(; token = @load_preference("readwrite_pat",
                                 @load_preference("readonly_pat", 
                                 Base.get(ENV, "AIRTABLE_KEY", nothing))))
     isnothing(token) && throw(ArgumentError("Environment does not have personal access token set. Must past api key directly"))
     return Credential(token)
+||||||| 764d019
+function Credential(; api_key=Base.get(ENV, "AIRTABLE_KEY", nothing))
+    isnothing(api_key) && throw(ArgumentError("Environment does not have `$AIRTABLE_KEY` set. Must past api key directly"))
+    return Credential(api_key)
+=======
+"""
+    set_pat(pat::String)
+
+Set `pat` to be the personal access token used by default
+in Airtable.jl operations.
+See also: [`Credential`](@ref)
+"""
+set_pat(pat) = @set_preferences!("PAT"=> pat)
+
+function _get_default_key()
+    @load_preference(
+        "PAT", # first choce - Preferences.jl key "PAT"
+        Base.get(ENV, "AIRTABLE_KEY", # fallback to env variable for backwards compat
+            nothing # if neither set, return nothing
+           )
+       )
 end
 
-Base.show(io::IO, ::Credential) = println(io, "Airtable.Credential(<secrets>)")
+function Credential(; api_key=_get_default_key())
+    isnothing(api_key) && throw(ArgumentError("Environment does not have default key set. Must past api key directly"))
+    return Credential(api_key)
+>>>>>>> pat
+end
+
+function Base.show(io::IO, cred::Credential)
+    m = match(r"^(pat[a-zA-Z0-9]+)\.[a-zA-Z0-9]+", cred.api_key)
+    isnothing(m) ? println(io, "Airtable.Credential(<secrets>)") :
+                   println(io, "Airtable.Credential(\"$(m[1])\")")
+end
 
 @testset "Credentials" begin
     key = Airtable.Credential()
     @test key isa Airtable.Credential
+<<<<<<< HEAD
     @test key.token isa String
-end
+end
+||||||| 764d019
+    @test key.api_key isa String
+end
+=======
+    @test key.api_key isa String
+end
+>>>>>>> pat