update to use Preferences.jl, and add docs for using PAT

.gitignore

@@ -5,4 +5,5 @@ Manifest.toml
 /docs/build/
 .vscode
 .envrc
-test/add_records.json
+test/add_records.json
+LocalPreferences.toml

Project.toml

@@ -7,12 +7,14 @@ version = "0.2.3"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 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

@@ -29,22 +29,34 @@ you should understand a few of the terms Airtable uses:
 
 All API operations also require that you provide authorization in the form of an API key.
 
-### [API key](@id apikey)
+### [Personal Access Token](@id apikey)
 
-To obtain your API key, go to your [account settings page](https://airtable.com/account)
-and click on the "generate API key" button.
-If you previously made a key, you can regenerate it, or just copy the one that's there.
+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.
 
-![Get airtable API key](img/api-key.png)
+![Create airtable token](img/create-token-1.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`.
+
+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.
+
+![Create airtable token 2](img/create-token-2.png)
 
 You can then create an [`Airtable.Credential`](@ref) using that key as a string,
-or set it as an environmental variable (`AIRTABLE_KEY` by default).
+set it as an environmental variable (`AIRTABLE_KEY` by default),
+or use `Preferences.jl` to set the "PAT" preference for this package.
 
 ```@docs
+set_pat
 Credential
 ```
 
-It is recommended that you use the environmental variable,
+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

@@ -9,6 +9,7 @@ using Dates
 using HTTP
 using JSON3
 using ProgressMeter
+using Preferences
 using ReTest
 
 const API_VERSION = "v0"

src/auth.jl

@@ -2,30 +2,55 @@
      Credential(; api_key)
 
 A credential object for Airtable.
-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)
 
 ```jldoctest; setup = :(using Airtable)
-# after running `export AIRTABLE_KEY=<api key>` in the shell
+# after running `Airtable.set_pat("patfh3gwMkFASf6Ue.<obscured>")`
 julia> key = Airtable.Credential()
-Airtable.Credential(<secrets>)
+Airtable.Credential("patfh3gwMkFASf6Ue")
 ```
 """
 struct Credential
     api_key::String
 end
 
-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"))
+"""
+    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
+
+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)
 end
 
-Base.show(io::IO, ::Credential) = println(io, "Airtable.Credential(<secrets>)")
+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
     @test key.api_key isa String
-end
+end