Skip to content

Commit 4af79f9

Browse files
razor-xseambot
razor-x
and
seambot
authored
Add note on was_confirmed_by_device for lock/unlock (#1055)
Co-authored-by: Seam Bot <seambot@getseam.com>
1 parent 59a7719 commit 4af79f9

9 files changed

Lines changed: 94 additions & 63 deletions

File tree

‎codegen/data/code-sample-definitions/action_attempts.yaml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
action_attempt_id: 5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f
1212
action_type: UNLOCK_DOOR
1313
error: null
14-
result: {}
14+
result:
15+
was_confirmed_by_device: false
1516
status: success
1617
- title: List action attempts
1718
description: Returns a list of the action attempts that you specify as an array of `action_attempt_id`s.
@@ -29,7 +30,8 @@
2930
- action_attempt_id: 5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f
3031
action_type: UNLOCK_DOOR
3132
error: null
32-
result: {}
33+
result:
34+
was_confirmed_by_device: false
3335
status: success
3436
- action_attempt_id: 3f2b1c8d-1b5e-4f8c-9c7d-9a8b7c6d5e4f
3537
action_type: LOCK_DOOR

‎codegen/data/code-sample-definitions/locks.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -349,7 +349,8 @@
349349
action_attempt_id: 5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f
350350
action_type: UNLOCK_DOOR
351351
error: null
352-
result: {}
352+
result:
353+
was_confirmed_by_device: false
353354
status: success
354355
- title: Simulate a keypad code entry
355356
description: Simulates the entry of a code on a keypad.

‎codegen/data/resource-sample-definitions/all-resources.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -409,7 +409,8 @@
409409
action_attempt_id: 5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f
410410
action_type: UNLOCK_DOOR
411411
error: null
412-
result: {}
412+
result:
413+
was_confirmed_by_device: false
413414
status: success
414415
- title: Card Access Method
415416
description: A card access method resource.

‎docs/api/_blueprint.json‎

Lines changed: 40 additions & 32 deletions
Large diffs are not rendered by default.

‎docs/api/acs/entrances/unlock.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Returns:
5151
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
5252
"action_type": "UNLOCK_DOOR",
5353
"error": null,
54-
"result": {},
54+
"result": { "was_confirmed_by_device": false },
5555
"status": "success"
5656
}
5757
```

‎docs/api/action_attempts/get.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ await seam.actionAttempts.get({
2626
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
2727
"action_type": "UNLOCK_DOOR",
2828
"error": null,
29-
"result": {},
29+
"result": { "was_confirmed_by_device": false },
3030
"status": "success"
3131
}
3232
```
@@ -56,7 +56,7 @@ EOF
5656
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
5757
"action_type": "UNLOCK_DOOR",
5858
"error": null,
59-
"result": {},
59+
"result": { "was_confirmed_by_device": false },
6060
"status": "success"
6161
}
6262
}
@@ -80,7 +80,7 @@ ActionAttempt(
8080
action_attempt_id="5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
8181
action_type="UNLOCK_DOOR",
8282
error=None,
83-
result={},
83+
result={"was_confirmed_by_device": false},
8484
status="success",
8585
)
8686
```
@@ -104,6 +104,7 @@ seam.action_attempts.get(action_attempt_id: "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0
104104
"action_type" => "UNLOCK_DOOR",
105105
"error" => nil,
106106
"result" => {
107+
was_confirmed_by_device: false,
107108
},
108109
"status" => "success",
109110
}
@@ -129,7 +130,7 @@ $seam->action_attempts->get(
129130
"action_attempt_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
130131
"action_type" => "UNLOCK_DOOR",
131132
"error" => null,
132-
"result" => [],
133+
"result" => ["was_confirmed_by_device" => false],
133134
"status" => "success",
134135
];
135136
```
@@ -152,7 +153,7 @@ seam action-attempts get --action_attempt_id "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e
152153
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
153154
"action_type": "UNLOCK_DOOR",
154155
"error": null,
155-
"result": {},
156+
"result": { "was_confirmed_by_device": false },
156157
"status": "success"
157158
}
158159
```

‎docs/api/action_attempts/list.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ await seam.actionAttempts.list({
3030
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
3131
"action_type": "UNLOCK_DOOR",
3232
"error": null,
33-
"result": {},
33+
"result": { "was_confirmed_by_device": false },
3434
"status": "success"
3535
},
3636
{
@@ -72,7 +72,7 @@ EOF
7272
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
7373
"action_type": "UNLOCK_DOOR",
7474
"error": null,
75-
"result": {},
75+
"result": { "was_confirmed_by_device": false },
7676
"status": "success"
7777
},
7878
{
@@ -110,7 +110,7 @@ seam.action_attempts.list(
110110
action_attempt_id="5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
111111
action_type="UNLOCK_DOOR",
112112
error=None,
113-
result={},
113+
result={"was_confirmed_by_device": false},
114114
status="success",
115115
),
116116
ActionAttempt(
@@ -145,6 +145,7 @@ seam.action_attempts.list(
145145
"action_type" => "UNLOCK_DOOR",
146146
"error" => nil,
147147
"result" => {
148+
was_confirmed_by_device: false,
148149
},
149150
"status" => "success",
150151
},
@@ -183,7 +184,7 @@ $seam->action_attempts->list(
183184
"action_attempt_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
184185
"action_type" => "UNLOCK_DOOR",
185186
"error" => null,
186-
"result" => [],
187+
"result" => ["was_confirmed_by_device" => false],
187188
"status" => "success",
188189
],
189190
[
@@ -215,7 +216,7 @@ seam action-attempts list --action_attempt_ids ["5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2
215216
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
216217
"action_type": "UNLOCK_DOOR",
217218
"error": null,
218-
"result": {},
219+
"result": { "was_confirmed_by_device": false },
219220
"status": "success"
220221
},
221222
{

‎docs/api/locks/unlock_door.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ await seam.locks.unlockDoor({
2626
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
2727
"action_type": "UNLOCK_DOOR",
2828
"error": null,
29-
"result": {},
29+
"result": { "was_confirmed_by_device": false },
3030
"status": "success"
3131
}
3232
```
@@ -56,7 +56,7 @@ EOF
5656
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
5757
"action_type": "UNLOCK_DOOR",
5858
"error": null,
59-
"result": {},
59+
"result": { "was_confirmed_by_device": false },
6060
"status": "success"
6161
}
6262
}
@@ -80,7 +80,7 @@ ActionAttempt(
8080
action_attempt_id="5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
8181
action_type="UNLOCK_DOOR",
8282
error=None,
83-
result={},
83+
result={"was_confirmed_by_device": false},
8484
status="success",
8585
)
8686
```
@@ -104,6 +104,7 @@ seam.locks.unlock_door(device_id: "be047431-bf00-4da6-9fc7-0a7796a9b57f")
104104
"action_type" => "UNLOCK_DOOR",
105105
"error" => nil,
106106
"result" => {
107+
was_confirmed_by_device: false,
107108
},
108109
"status" => "success",
109110
}
@@ -127,7 +128,7 @@ $seam->locks->unlock_door(device_id: "be047431-bf00-4da6-9fc7-0a7796a9b57f");
127128
"action_attempt_id" => "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
128129
"action_type" => "UNLOCK_DOOR",
129130
"error" => null,
130-
"result" => [],
131+
"result" => ["was_confirmed_by_device" => false],
131132
"status" => "success",
132133
];
133134
```
@@ -150,7 +151,7 @@ seam locks unlock-door --device_id "be047431-bf00-4da6-9fc7-0a7796a9b57f"
150151
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
151152
"action_type": "UNLOCK_DOOR",
152153
"error": null,
153-
"result": {},
154+
"result": { "was_confirmed_by_device": false },
154155
"status": "success"
155156
}
156157
```
@@ -199,7 +200,7 @@ Returns:
199200
"action_attempt_id": "5f4e3d2c-1b0a-9f8e-7d6c-5b4a3c2d1e0f",
200201
"action_type": "UNLOCK_DOOR",
201202
"error": null,
202-
"result": {},
203+
"result": { "was_confirmed_by_device": false },
203204
"status": "success"
204205
}
205206
```

‎docs/products/smart-locks/lock-and-unlock.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ When you send a command to a smart lock, it might take a while for Seam to confi
1212

1313
To ensure that the action has been successfully executed, we advise checking the status of the action attempt object by polling the ["Get Action Attempt" request](../../api/action_attempts/get.md). Once Seam has successfully confirmed the action, the action attempt's `status` will indicate `success`.
1414

15-
For those who prefer using webhooks to verify the success of an action, we'll soon introduce events that confirm an action's success.
15+
Some providers and device models cannot confirm whether the physical lock or unlock happened in a reasonable time or at all. In those cases, a successful action attempt can still include `action_attempt.result.was_confirmed_by_device = false`.
1616

1717
***
1818

@@ -401,7 +401,7 @@ device=$(
401401
}')
402402

403403
# Confirm that the device can remotely unlock.
404-
if $(jq -r '.device.can_remotely_lock' <<< ${device}); then \
404+
if $(jq -r '.device.can_remotely_unlock' <<< ${device}); then \
405405
# Perform the unlock operation.
406406
curl -X 'POST' \
407407
'https://connect.getseam.com/locks/unlock_door' \
@@ -456,7 +456,9 @@ if (device.can_remotely_unlock) {
456456
status: 'success',
457457
action_attempt_id: '11111111-2222-3333-4444-555555555555',
458458
action_type: 'UNLOCK_DOOR',
459-
result: {},
459+
result: {
460+
was_confirmed_by_device: false
461+
},
460462
error: null
461463
}
462464
}
@@ -509,7 +511,9 @@ if ($device->can_remotely_unlock) {
509511
"action_attempt_id":"11111111-2222-3333-4444-555555555555",
510512
"action_type":"UNLOCK_DOOR",
511513
"error":null,
512-
"result":{},
514+
"result":{
515+
"was_confirmed_by_device":false
516+
},
513517
"status":"success"
514518
}
515519
```
@@ -689,6 +693,10 @@ seam.Locks.LockDoor(deviceId: "11111111-1111-1111-1111-444444444444");
689693

690694
Use the `action_attempt_id` from the prior response to make a [Get Action Attempt request](../../api/action_attempts/get.md). When the action attempt's `status` changes to `success`, it indicates the action has been successful.
691695

696+
{% hint style="info" %}
697+
Some providers and device models do not confirm whether a lock or unlock completed on the physical device. In those cases, the action attempt can still succeed while `action_attempt.result.was_confirmed_by_device` is `false`. Use this property to set the right expectation in your UI, especially for unlock flows.
698+
{% endhint %}
699+
692700
{% tabs %}
693701
{% tab title="Python" %}
694702
**Request:**
@@ -703,7 +711,7 @@ seam.action_attempts.get(action_attempt_id="11111111-2222-3333-4444-555555555555
703711
ActionAttempt(action_attempt_id='11111111-2222-3333-4444-555555555555',
704712
action_type='LOCK_DOOR',
705713
status='success',
706-
result={},
714+
result={'was_confirmed_by_device': True},
707715
error=None)
708716
```
709717
{% endtab %}
@@ -731,7 +739,9 @@ curl -X 'GET' \
731739
"status": "success",
732740
"action_attempt_id": "11111111-2222-3333-4444-555555555555",
733741
"action_type": "LOCK_DOOR",
734-
"result": {},
742+
"result": {
743+
"was_confirmed_by_device": true
744+
},
735745
"error": null
736746
},
737747
"ok": true
@@ -753,7 +763,9 @@ await seam.actionAttempts.get({action_attempt_id: "11111111-2222-3333-4444-55555
753763
status: 'success',
754764
action_attempt_id: '11111111-2222-3333-4444-555555555555',
755765
action_type: 'LOCK_DOOR',
756-
result: {},
766+
result: {
767+
was_confirmed_by_device: true
768+
},
757769
error: null
758770
}
759771
```
@@ -773,7 +785,7 @@ client.action_attempts.get(action_attempt_id: "11111111-2222-3333-4444-555555555
773785
status="success"
774786
action_attempt_id="11111111-2222-3333-4444-555555555555"
775787
action_type="LOCK_DOOR"
776-
result={}>
788+
result={"was_confirmed_by_device"=>true}>
777789
```
778790
{% endtab %}
779791

@@ -791,7 +803,9 @@ $seam->action_attempts->get(action_attempt_id: "11111111-2222-3333-4444-55555555
791803
"action_attempt_id":"11111111-2222-3333-4444-555555555555",
792804
"action_type":"LOCK_DOOR",
793805
"error":null,
794-
"result":{},
806+
"result":{
807+
"was_confirmed_by_device":true
808+
},
795809
"status":"success"
796810
}
797811
```
@@ -811,7 +825,9 @@ seam.ActionAttempts.Get("11111111-2222-3333-4444-555555555555");
811825
"status": "success",
812826
"action_type": "LOCK_DOOR",
813827
"action_attempt_id": "11111111-2222-3333-4444-555555555555",
814-
"result": {},
828+
"result": {
829+
"was_confirmed_by_device": true
830+
},
815831
"error": null
816832
}
817833
```

0 commit comments

Comments
 (0)