Skip to content

Commit 4b897ce

Browse files
tabtab
committed
feat(docs): Add documentation
Added a GitHub Actions workflow to build and deploy documentation using MkDocs Updated README to include features and installation instructions
1 parent 7b8a696 commit 4b897ce

File tree

6 files changed

+308
-1
lines changed

6 files changed

+308
-1
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Docs
2+
on:
3+
push:
4+
branches:
5+
- master
6+
workflow_dispatch:
7+
concurrency:
8+
group: ${{ github.workflow }}@${{ github.ref }}
9+
cancel-in-progress: true
10+
permissions:
11+
contents: write
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Download source
17+
uses: actions/checkout@v4
18+
- name: Install Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: '3.11'
22+
- name: Install dependencies
23+
run: |
24+
pip install --upgrade pip
25+
pip install mkdocs mkdocs-material mkdocs-minify-plugin
26+
- name: Build
27+
run: mkdocs build --strict
28+
- name: Deploy
29+
run: mkdocs gh-deploy --force

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,18 @@
33
Golang client for the Mobile-ID API (https://www.mobile-id.lt/en/).
44
It is a simple wrapper around the API, which helps easily integrate Mobile-ID authentication into Golang applications.
55

6+
## Features
7+
8+
- Flexible client configuration
9+
- Concurrent processing
10+
- Optional TLS configuration (certificate pinning)
11+
612
## Installation
713

814
Use `go get` to install the package
915

1016
```sh
11-
go get github.com/tab/mobileid
17+
go get -u github.com/tab/mobileid
1218
```
1319

1420
## Usage
@@ -199,6 +205,7 @@ func main() {
199205
200206
## Documentation
201207
208+
- [Documentation](https://tab.github.io/mobileid)
202209
- [GoDoc](https://pkg.go.dev/github.com/tab/mobileid)
203210
- [Mobile-ID Documentation](https://github.com/SK-EID/MID)
204211

‎docs/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Golang client for the Mobile-ID API (https://www.mobile-id.lt/en/).
2+
It is a simple wrapper around the API, which helps easily integrate Mobile-ID authentication into Golang applications.
3+
4+
## Features
5+
6+
- Flexible client configuration
7+
- Concurrent processing
8+
- Optional TLS configuration (certificate pinning)
9+
10+
## Contents
11+
12+
- [Installation](installation.md)
13+
- [Usage](usage.md)

‎docs/installation.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Installation
2+
3+
Use `go get` to install the package
4+
5+
```sh
6+
go get -u github.com/tab/mobileid
7+
```

‎docs/usage.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Usage
2+
3+
## Configure a client
4+
5+
Create a new client using `NewClient()` and customize its configuration using chainable methods.
6+
7+
```go
8+
package main
9+
10+
import (
11+
"context"
12+
"log"
13+
"time"
14+
15+
"github.com/tab/mobileid"
16+
)
17+
18+
func main() {
19+
client := mobileid.NewClient().
20+
WithRelyingPartyName("DEMO").
21+
WithRelyingPartyUUID("00000000-0000-0000-0000-000000000000").
22+
WithHashType("SHA512").
23+
WithText("Enter PIN1").
24+
WithTextFormat("GSM-7").
25+
WithLanguage("ENG").
26+
WithURL("https://tsp.demo.sk.ee/mid-api").
27+
WithTimeout(60 * time.Second)
28+
29+
if err := client.Validate(); err != nil {
30+
log.Fatal("Invalid configuration:", err)
31+
}
32+
33+
// Further processing...
34+
}
35+
```
36+
37+
Check client default configuration values:
38+
39+
```go
40+
const (
41+
Text = "Enter PIN1"
42+
TextFormat = "GSM-7"
43+
Language = "ENG"
44+
Timeout = requests.Timeout
45+
URL = "https://tsp.demo.sk.ee/mid-api"
46+
)
47+
48+
cfg := &config.Config{
49+
HashType: utils.HashTypeSHA512,
50+
Text: Text,
51+
TextFormat: TextFormat,
52+
Language: Language,
53+
URL: URL,
54+
Timeout: Timeout,
55+
}
56+
```
57+
58+
## Start authentication
59+
60+
Initiate a new authentication session with the `Mobile-ID` provider by calling `CreateSession`.
61+
This function generates a random hash, constructs the session request, and returns a session that includes an identifier and a verification code.
62+
63+
```go
64+
func main() {
65+
// Create a client...
66+
67+
68+
phoneNumber := "+37268000769"
69+
identity := "60001017869"
70+
71+
session, err := client.CreateSession(context.Background(), phoneNumber, identity)
72+
if err != nil {
73+
log.Fatal("Error creating session:", err)
74+
}
75+
76+
fmt.Println("Session created:", session)
77+
}
78+
```
79+
80+
## Fetch authentication session
81+
82+
```go
83+
func main() {
84+
// Create a client...
85+
86+
person, err := client.FetchSession(context.Background(), sessionId)
87+
if err != nil {
88+
log.Fatal("Error fetching session:", err)
89+
}
90+
91+
fmt.Println("Session status:", session.State)
92+
}
93+
```
94+
95+
## Async example
96+
97+
For applications requiring the processing of multiple authentication sessions simultaneously, `Mobile-ID` provides a worker model.
98+
Create a worker using `NewWorker`, configure its concurrency and queue size, and then start processing.
99+
100+
```go
101+
package main
102+
103+
import (
104+
"context"
105+
"fmt"
106+
"sync"
107+
"time"
108+
109+
"github.com/tab/mobileid"
110+
)
111+
112+
func main() {
113+
client := mobileid.NewClient().
114+
WithRelyingPartyName("DEMO").
115+
WithRelyingPartyUUID("00000000-0000-0000-0000-000000000000").
116+
WithHashType("SHA512").
117+
WithText("Enter PIN1").
118+
WithTextFormat("GSM-7").
119+
WithLanguage("ENG").
120+
WithURL("https://tsp.demo.sk.ee/mid-api").
121+
WithTimeout(60 * time.Second)
122+
123+
identities := map[string]string{
124+
"51307149560": "+37269930366",
125+
"60001017869": "+37268000769",
126+
"60001018800": "+37200000566",
127+
"60001019939": "+37200000266",
128+
"60001019947": "+37207110066",
129+
"60001019950": "+37201100266",
130+
"60001019961": "+37200000666",
131+
"60001019972": "+37201200266",
132+
"60001019983": "+37213100266",
133+
"50001018908": "+37266000266",
134+
}
135+
136+
worker := mobileid.NewWorker(client).
137+
WithConcurrency(50).
138+
WithQueueSize(100)
139+
140+
ctx := context.Background()
141+
142+
worker.Start(ctx)
143+
defer worker.Stop()
144+
145+
var wg sync.WaitGroup
146+
147+
for identity, phoneNumber := range identities {
148+
wg.Add(1)
149+
150+
session, err := client.CreateSession(ctx, phoneNumber, identity)
151+
if err != nil {
152+
fmt.Println("Error creating session:", err)
153+
wg.Done()
154+
}
155+
fmt.Println("Session created:", session)
156+
157+
resultCh := worker.Process(ctx, session.Id)
158+
go func() {
159+
defer wg.Done()
160+
result := <-resultCh
161+
if result.Err != nil {
162+
fmt.Println("Error fetching session:", result.Err)
163+
} else {
164+
fmt.Println("Fetched person:", result.Person)
165+
}
166+
}()
167+
}
168+
169+
wg.Wait()
170+
}
171+
```
172+
173+
## Certificate pinning (optional)
174+
175+
```go
176+
package main
177+
178+
import (
179+
"context"
180+
"fmt"
181+
"sync"
182+
"time"
183+
184+
"github.com/tab/mobileid"
185+
)
186+
187+
func main() {
188+
manager, err := mobileid.NewCertificateManager("./certs")
189+
if err != nil {
190+
fmt.Println("Failed to create certificate manager:", err)
191+
}
192+
tlsConfig := manager.TLSConfig()
193+
194+
client := mobileid.NewClient().
195+
WithRelyingPartyName("DEMO").
196+
WithRelyingPartyUUID("00000000-0000-0000-0000-000000000000").
197+
WithHashType("SHA512").
198+
WithText("Enter PIN1").
199+
WithTextFormat("GSM-7").
200+
WithLanguage("ENG").
201+
WithURL("https://tsp.demo.sk.ee/mid-api").
202+
WithTimeout(60 * time.Second).
203+
WithTLSConfig(tlsConfig)
204+
205+
// Further processing...
206+
```
207+
208+
```sh
209+
Session created: &{b2769811-16de-42f1-a06e-c580d07c1298 5960}
210+
Fetched person: &{PNOEE-60001017869 60001017869 EID2016 TESTNUMBER}
211+
```
212+
213+
- **b2769811-16de-42f1-a06e-c580d07c1298** – session id
214+
- **5960** – verification code
215+
216+
217+
- **PNOEE-60001017869** – formatted identity
218+
- **60001017869** – personal identification code
219+
- **EID2016** – person first name
220+
- **TESTNUMBER** – person last name
221+

‎mkdocs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
site_name: mobileid
2+
site_url: https://tab.github.io/mobileid
3+
site_author: tab
4+
site_description: Golang client for the Mobile-ID API
5+
6+
repo_name: tab/mobileid
7+
repo_url: https://github.com/tab/mobileid
8+
9+
nav:
10+
- Home: index.md
11+
- Installation: installation.md
12+
- Usage: usage.md
13+
14+
docs_dir: docs
15+
site_dir: site
16+
17+
theme:
18+
name: material
19+
language: en
20+
palette:
21+
- scheme: default
22+
media: "(prefers-color-scheme: light)"
23+
primary: blue-grey
24+
25+
plugins:
26+
- search
27+
- minify:
28+
minify_html: true
29+
minify_js: true
30+
minify_css: true

0 commit comments

Comments
 (0)