A macOS CLI tool that exports original photos and videos from the macOS Photos library using PhotoKit.
feat: mark shared-album unavailable assets (0.4.0)
- AssetHandle exposes isShared from PHAsset.sourceType == .typeCloudShared
- ExportError gains unavailable flag (backward-compatible)
- PhotoExporter short-circuits shared-album PhotoKit failures instead of
retrying via AppleScript, which also fails via the same shared-stream
pipeline after a 5-minute server-side timeout
+97
-5
+12
CHANGELOG.md
+12
CHANGELOG.md
···
1
1
# Changelog
2
2
3
+
## 0.4.0
4
+
5
+
- `AssetHandle` exposes `isShared: Bool` (from `PHAsset.sourceType == .typeCloudShared`)
6
+
- `ExportError` gains an `unavailable: Bool` flag for failures that should
7
+
not be retried (e.g. shared-album assets whose iCloud derivative has failed
8
+
server-side). Backward-compatible default `false`; decoder tolerates
9
+
payloads without the field.
10
+
- `PhotoExporter.export` short-circuits shared-album assets that fail
11
+
PhotoKit: the AppleScript fallback goes through the same shared-stream
12
+
pipeline and also fails (after a 5-minute server-side timeout), so we
13
+
mark these as `unavailable` immediately instead of retrying.
14
+
3
15
## 0.3.4
4
16
5
17
- Include iCloud Shared Photo Library assets in `enumerateAssets()` and
+16
-1
Sources/LadderKit/Models.swift
+16
-1
Sources/LadderKit/Models.swift
···
40
40
public struct ExportError: Codable, Sendable {
41
41
public let uuid: String
42
42
public let message: String
43
+
/// The asset cannot be downloaded from iCloud and retries are pointless
44
+
/// (e.g. shared-album asset whose owner's derivative is unreachable).
45
+
public let unavailable: Bool
43
46
44
-
public init(uuid: String, message: String) {
47
+
public init(uuid: String, message: String, unavailable: Bool = false) {
45
48
self.uuid = uuid
46
49
self.message = message
50
+
self.unavailable = unavailable
51
+
}
52
+
53
+
private enum CodingKeys: String, CodingKey {
54
+
case uuid, message, unavailable
55
+
}
56
+
57
+
public init(from decoder: Decoder) throws {
58
+
let c = try decoder.container(keyedBy: CodingKeys.self)
59
+
uuid = try c.decode(String.self, forKey: .uuid)
60
+
message = try c.decode(String.self, forKey: .message)
61
+
unavailable = try c.decodeIfPresent(Bool.self, forKey: .unavailable) ?? false
47
62
}
48
63
}
+23
-3
Sources/LadderKit/PhotoExporter.swift
+23
-3
Sources/LadderKit/PhotoExporter.swift
···
59
59
var allResults: [ExportResult] = []
60
60
var allErrors: [ExportError] = []
61
61
var photoKitFailedUUIDs: [String] = []
62
+
// Shared-album assets that fail PhotoKit go through iCloud's shared-stream
63
+
// pipeline, which the AppleScript path also uses — retrying via AppleScript
64
+
// just waits ~5min for the same server-side error. Short-circuit these.
62
65
for result in exportResults {
63
66
switch result {
64
67
case .success(let exportResult):
65
68
allResults.append(exportResult)
66
69
case .failure(let pair):
67
-
photoKitFailedUUIDs.append(pair.uuid)
70
+
if pair.isShared {
71
+
allErrors.append(ExportError(
72
+
uuid: pair.uuid,
73
+
message: "Shared-album asset unavailable from iCloud: \(pair.message)",
74
+
unavailable: true,
75
+
))
76
+
} else {
77
+
photoKitFailedUUIDs.append(pair.uuid)
78
+
}
68
79
}
69
80
}
70
81
···
167
178
originalFilename: handle.originalFilename
168
179
)
169
180
} catch {
170
-
return .failure(ExportErrorPair(uuid: uuid, message: error.localizedDescription))
181
+
return .failure(ExportErrorPair(
182
+
uuid: uuid,
183
+
message: error.localizedDescription,
184
+
isShared: handle.isShared,
185
+
))
171
186
}
172
187
173
188
// Create empty file for writing
···
192
207
} catch {
193
208
// Clean up the empty/partial file so AppleScript fallback can reuse the path
194
209
try? FileManager.default.removeItem(at: destURL)
195
-
return .failure(ExportErrorPair(uuid: uuid, message: error.localizedDescription))
210
+
return .failure(ExportErrorPair(
211
+
uuid: uuid,
212
+
message: error.localizedDescription,
213
+
isShared: handle.isShared,
214
+
))
196
215
}
197
216
}
198
217
}
···
201
220
struct ExportErrorPair: Error, Sendable {
202
221
let uuid: String
203
222
let message: String
223
+
let isShared: Bool
204
224
}
205
225
206
226
public enum ExportFailure: LocalizedError {
+9
-1
Sources/LadderKit/PhotoLibrary.swift
+9
-1
Sources/LadderKit/PhotoLibrary.swift
···
21
21
public protocol AssetHandle: Sendable {
22
22
var originalFilename: String { get }
23
23
var resourceType: PHAssetResourceType { get }
24
+
/// True for iCloud Shared Album assets (`PHAsset.sourceType == .typeCloudShared`).
25
+
/// These go through a different iCloud pipeline that can fail server-side
26
+
/// with no recoverable fallback, so callers should skip retry paths on failure.
27
+
var isShared: Bool { get }
24
28
25
29
/// Write the asset's original data to a file, streaming chunks to the handler.
26
30
/// Each chunk is delivered to `chunkHandler` before being written, enabling
···
48
52
guard let resource = resources.first(where: { $0.type == .photo || $0.type == .video })
49
53
?? resources.first
50
54
else { return }
51
-
result[asset.localIdentifier] = PhotoKitAssetHandle(resource: resource)
55
+
result[asset.localIdentifier] = PhotoKitAssetHandle(
56
+
resource: resource,
57
+
isShared: asset.sourceType == .typeCloudShared,
58
+
)
52
59
}
53
60
return result
54
61
}
···
95
102
96
103
struct PhotoKitAssetHandle: AssetHandle {
97
104
let resource: PHAssetResource
105
+
let isShared: Bool
98
106
99
107
var originalFilename: String { resource.originalFilename }
100
108
var resourceType: PHAssetResourceType { resource.type }
+1
Tests/AppleScriptExporterTests.swift
+1
Tests/AppleScriptExporterTests.swift
+36
Tests/PhotoExporterTests.swift
+36
Tests/PhotoExporterTests.swift
···
33
33
let originalFilename: String
34
34
let resourceType: PHAssetResourceType
35
35
let data: Data
36
+
var isShared: Bool = false
37
+
var writeError: Error?
36
38
37
39
func writeData(
38
40
to destinationURL: URL,
39
41
networkAccessAllowed: Bool,
40
42
chunkHandler: @escaping @Sendable (Data) -> Void
41
43
) async throws -> Int64 {
44
+
if let writeError { throw writeError }
42
45
let handle = try FileHandle(forWritingTo: destinationURL)
43
46
// Deliver in chunks to simulate streaming
44
47
let chunkSize = max(data.count / 3, 1)
···
127
130
#expect(response.results[0].uuid == "found-1")
128
131
#expect(response.errors.count == 1)
129
132
#expect(response.errors[0].uuid == "missing-1")
133
+
}
134
+
135
+
@Test("shared-album asset failure is marked unavailable and skips AppleScript fallback")
136
+
func sharedAssetUnavailable() async throws {
137
+
let tempDir = FileManager.default.temporaryDirectory
138
+
.appendingPathComponent("ladder-test-\(UUID().uuidString)")
139
+
try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
140
+
defer { try? FileManager.default.removeItem(at: tempDir) }
141
+
142
+
let library = MockPhotoLibrary(assets: [
143
+
"shared-1": MockAssetHandle(
144
+
originalFilename: "IMG_7666.HEIC",
145
+
resourceType: .photo,
146
+
data: Data(),
147
+
isShared: true,
148
+
writeError: NSError(domain: "PHPhotosErrorDomain", code: 3169)
149
+
)
150
+
])
151
+
152
+
// Script exporter that would succeed if called — we assert it is NOT called
153
+
// for shared-album assets. A simple way: provide a stub that would produce
154
+
// a file, and check that no result was produced via it.
155
+
let exporter = PhotoExporter(
156
+
stagingDir: tempDir,
157
+
library: library,
158
+
scriptExporter: nil
159
+
)
160
+
let response = await exporter.export(uuids: ["shared-1"])
161
+
162
+
#expect(response.results.isEmpty)
163
+
#expect(response.errors.count == 1)
164
+
#expect(response.errors[0].uuid == "shared-1")
165
+
#expect(response.errors[0].unavailable == true)
130
166
}
131
167
132
168
@Test("sanitizes PHAsset-style identifiers in file paths")